این مقاله به صورت جامع و گام‌به‌گام، نحوه پیاده‌سازی یک سیستم Localization چندزبانه در ASP.NET Core MVC را تشریح می‌کند که در آن، تغییر زبان هیچ تأثیری بر URL صفحه نخواهد داشت. ما از کوکی (Cookie) برای ذخیره و بازیابی زبان انتخابی کاربر استفاده خواهیم کرد.

گام اول: پیکربندی سرویس‌های Localization

اولین قدم، افزودن و پیکربندی سرویس‌های مورد نیاز برای Localization در برنامه ASP.NET Core است. این کار در فایل Program.cs (یا Startup.cs در نسخه‌های قدیمی‌تر) انجام می‌شود.

ابتدا، سرویس‌های Localization را به مجموعه‌ی سرویس‌های برنامه اضافه می‌کنیم. این کار با فراخوانی متد AddLocalization انجام می‌شود. همچنین می‌توانیم مسیر پیش‌فرض فایل‌های منابع (Resource Files) را در اینجا مشخص کنیم.

// Program.cs

var builder = WebApplication.CreateBuilder(args);

// افزودن سرویس‌های Localization
builder.Services.AddLocalization(options => options.ResourcesPath = "Resources");

builder.Services.AddControllersWithViews()
    .AddViewLocalization() // پشتیبانی از Localization در View ها
    .AddDataAnnotationsLocalization(); // پشتیبانی از Localization برای Data Annotations

// ... سایر سرویس‌ها

در مرحله بعد، باید RequestLocalizationMiddleware را به خط لوله (Pipeline) درخواست برنامه اضافه کنیم. این Middleware مسئولیت تعیین زبان (Culture) مناسب برای هر درخواست را بر عهده دارد. ما لیستی از زبان‌های پشتیبانی شده و زبان پیش‌فرض را تعریف کرده و به Middleware معرفی می‌کنیم.

// Program.cs

var app = builder.Build();

// تعریف زبان‌های پشتیبانی شده
var supportedCultures = new[] { "en-US", "fa-IR" };
var localizationOptions = new RequestLocalizationOptions()
    .SetDefaultCulture(supportedCultures[0]) // تنظیم زبان پیش‌فرض (انگلیسی)
    .AddSupportedCultures(supportedCultures) // افزودن زبان‌های پشتیبانی شده
    .AddSupportedUICultures(supportedCultures); // افزودن زبان‌های UI پشتیبانی شده

// استفاده از Middleware
app.UseRequestLocalization(localizationOptions);

// ... سایر Middleware ها

app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();

app.MapControllerRoute(
    name: "default",
    pattern: "{controller=Home}/{action=Index}/{id?}");

app.Run();

در پیکربندی بالا، ما RequestLocalizationOptions را ایجاد کرده و زبان‌های انگلیسی (en-US) و فارسی (fa-IR) را به عنوان زبان‌های پشتیبانی شده تعریف نموده‌ایم.

گام دوم: ایجاد فایل‌های منابع (Resource Files)

فایل‌های منابع با پسوند .resx حاوی ترجمه‌های متون برنامه به زبان‌های مختلف هستند. این فایل‌ها به صورت زوج‌های کلید-مقدار (Key-Value) عمل می‌کنند. برای هر زبان پشتیبانی شده، یک فایل .resx مجزا ایجاد می‌شود.

مطابق با مسیری که در Program.cs مشخص کردیم (Resources)، یک پوشه به همین نام در ریشه پروژه ایجاد کنید. ساختار نام‌گذاری فایل‌های منابع بسیار مهم است. برای مثال، اگر می‌خواهیم متون مربوط به HomeController را ترجمه کنیم، ساختار فایل‌ها به شکل زیر خواهد بود:

• Resources/Controllers/HomeController.en-US.resx (برای زبان انگلیسی)

• Resources/Controllers/HomeController.fa-IR.resx (برای زبان فارسی)

هر فایل .resx شامل یک جدول است که در آن Name همان کلید و Value همان متن ترجمه شده است.

مثال برای HomeController.fa-IR.resx:

مثال برای HomeController.en-US.resx:

گام سوم: استفاده از متون ترجمه شده در View ها

برای دسترسی به مقادیر موجود در فایل‌های منابع از داخل View ها، از سرویس IViewLocalizer استفاده می‌کنیم. این سرویس را می‌توان به سادگی در بالای فایل Razor مربوطه @inject کرد.

@* Views/Home/Index.cshtml *@

@using Microsoft.AspNetCore.Mvc.Localization
@inject IViewLocalizer Localizer

@{
    ViewData["Title"] = Localizer["Welcome"];
}

<h1>@Localizer["Welcome"]</h1>
<p>@Localizer["HelloWorld"]</p>

IViewLocalizer به طور خودکار بر اساس زبان فعلی درخواست، فایل .resx مناسب را پیدا کرده و مقدار متناظر با کلید ارائه شده را برمی‌گرداند.

گام چهارم: پیاده‌سازی انتخابگر زبان (Language Switcher)

این بخش مهم‌ترین قسمت پیاده‌سازی ماست. ما می‌خواهیم به کاربر اجازه دهیم زبان را تغییر دهد و این انتخاب را برای درخواست‌های بعدی او به خاطر بسپاریم، بدون اینکه URL تغییر کند. برای این کار از کوکی استفاده می‌کنیم.

ایجاد یک Partial View برای انتخاب زبان

یک Partial View ایجاد می‌کنیم که لیستی از زبان‌های پشتیبانی شده را نمایش دهد و به کاربر امکان انتخاب دهد.

@* Views/Shared/_SelectLanguagePartial.cshtml *@

@using Microsoft.AspNetCore.Builder
@using Microsoft.AspNetCore.Localization
@using Microsoft.Extensions.Options

@inject IOptions<RequestLocalizationOptions> LocOptions

@{
    var requestCulture = Context.Features.Get<IRequestCultureFeature>();
    var cultureItems = LocOptions.Value.SupportedUICultures
        .Select(c => new SelectListItem { Value = c.Name, Text = c.NativeName })
        .ToList();
}

<form asp-action="SetLanguage" asp-controller="Home"
      asp-route-returnUrl="@Context.Request.Path@Context.Request.QueryString"
      method="post" class="form-horizontal" role="form">
    <label>Language:</label>
    <select name="culture" asp-for="@requestCulture.RequestCulture.UICulture.Name"
            asp-items="cultureItems" onchange="this.form.submit();"></select>
</form>

این فرم یک dropdown (تگ select) را نمایش می‌دهد. با تغییر زبان توسط کاربر، فرم به اکشن SetLanguage در HomeController ارسال می‌شود. ما همچنین URL فعلی را به عنوان returnUrl ارسال می‌کنیم تا پس از تغییر زبان، کاربر به همان صفحه بازگردانده شود.

ایجاد اکشن متد در کنترلر

حالا باید اکشن SetLanguage را در HomeController پیاده‌سازی کنیم. این اکشن مسئول ایجاد کوکی برای ذخیره زبان انتخابی کاربر است.

// Controllers/HomeController.cs

using Microsoft.AspNetCore.Localization;
using Microsoft.AspNetCore.Mvc;

public class HomeController : Controller
{
    // ... سایر اکشن‌ها

    [HttpPost]
    public IActionResult SetLanguage(string culture, string returnUrl)
    {
        Response.Cookies.Append(
            CookieRequestCultureProvider.DefaultCookieName,
            CookieRequestCultureProvider.MakeCookieValue(new RequestCulture(culture)),
            new CookieOptions { Expires = DateTimeOffset.UtcNow.AddYears(1) }
        );

        return LocalRedirect(returnUrl);
    }
}

در این کد:

1. یک کوکی با نام پیش‌فرض (.AspNetCore.Culture) ایجاد می‌کنیم.

2. مقدار کوکی را با استفاده از MakeCookieValue و زبان انتخاب شده (culture) تنظیم می‌کنیم.

3. یک تاریخ انقضا برای کوکی (مثلاً یک سال) در نظر می‌گیریم تا انتخاب کاربر پایدار بماند.

4. در نهایت، کاربر را به صفحه‌ای که از آن آمده بود (returnUrl) هدایت می‌کنیم.

CookieRequestCultureProvider که به طور پیش‌فرض توسط RequestLocalizationMiddleware فعال است، به طور خودکار این کوکی را در درخواست‌های بعدی خوانده و زبان برنامه را بر اساس آن تنظیم می‌کند.

حالا کافی است Partial View انتخابگر زبان را در فایل _Layout.cshtml یا هر جای دیگری که می‌خواهید، قرار دهید.

@* Views/Shared/_Layout.cshtml *@

<header>
    <nav>
        ...
        <div>
            <partial name="_SelectLanguagePartial" />
        </div>
        ...
    </nav>
</header>

جمع‌بندی

با دنبال کردن مراحل فوق، شما یک سیستم Localization چندزبانه کارآمد را در برنامه ASP.NET Core MVC خود پیاده‌سازی کرده‌اید که زبان انتخابی کاربر را از طریق کوکی مدیریت می‌کند و URL صفحات در تمام زبان‌ها ثابت باقی می‌ماند. این رویکرد نه تنها تجربه کاربری یکپارچه‌ای را فراهم می‌کند، بلکه از پیچیدگی‌های مربوط به مدیریت مسیرها (Routing) برای زبان‌های مختلف نیز جلوگیری می‌نماید.

این روش به راحتی قابل توسعه است؛ برای افزودن یک زبان جدید، کافی است آن را به لیست supportedCultures در Program.cs اضافه کرده و فایل .resx مربوط به آن را ایجاد نمایید.