共用方式為


在當地語系化的 ASP.NET Core 應用程式中實作可依據每項要求選取語言/文化特性的策略

注意

這不是這篇文章的最新版本。 如需目前版本,請參閱本文的 .NET 8 版本

警告

不再支援此版本的 ASP.NET Core。 如需詳細資訊,請參閱 .NET 和 .NET Core 支援原則。 如需目前版本,請參閱本文的 .NET 8 版本

重要

這些發行前產品的相關資訊在產品正式發行前可能會有大幅修改。 Microsoft 對此處提供的資訊,不做任何明確或隱含的瑕疵擔保。

如需目前版本,請參閱本文的 .NET 8 版本

Hisham Bin AteyaDamien BowdenBart Calixto, Nadeem AfanaRick Anderson

當地語系化應用程式的其中一項工作是實作策略,以針對應用程式傳回的每個回應選取適當的文化特性。

設定當地語系化中介軟體

您可以在當地語系化中介軟體中,設定要求目前的文化特性。 已在 Program.cs 中啟用當地語系化中介軟體。 您必須在可能檢查要求文化特性的任何中介軟體之前,設定當地語系化中介軟體 (例如 app.UseMvcWithDefaultRoute())。

builder.Services.Configure<RequestLocalizationOptions>(options =>
{
    var supportedCultures = new[] { "en-US", "fr" };
    options.SetDefaultCulture(supportedCultures[0])
        .AddSupportedCultures(supportedCultures)
        .AddSupportedUICultures(supportedCultures);
});

UseRequestLocalization 會初始化 RequestLocalizationOptions 物件。 在每次要求時,系統會列舉 RequestLocalizationOptions 中的 RequestCultureProvider 清單,並使用能成功判斷要求的文化特性的第一個提供者。 預設的提供者是來自 RequestLocalizationOptions 類別:

  1. QueryStringRequestCultureProvider
  2. CookieRequestCultureProvider
  3. AcceptLanguageHeaderRequestCultureProvider

預設清單會由針對性高到低來排列。 在本文稍後,您會了解如何變更順序,甚至新增自訂的文化特性提供者。 如果沒有任何提供者可以判斷要求的文化特性,即會使用 DefaultRequestCulture

QueryStringRequestCultureProvider

某些應用程式會使用查詢字串來設定 CultureInfo。 若是使用 cookie 或 Accept-Language 標頭方法的應用程式,您可以將查詢字串新增至 URL 以偵錯和測試程式碼。 系統預設會將 QueryStringRequestCultureProvider 登錄為 RequestCultureProvider 清單中的第一個當地語系化提供者。 您應傳遞查詢字串參數 cultureui-culture。 下列範例會設定西班牙文/墨西哥的特定文化特性 (語言和地區):

http://localhost:5000/?culture=es-MX&ui-culture=es-MX

如果只傳入 cultureui-culture,則查詢字串提供者會使用傳入的值來設定這兩個值。 例如,若只設定文化特性,即會同時設定 CultureUICulture

http://localhost:5000/?culture=es-MX

CookieRequestCultureProvider

生產環境應用程式通常會提供一個機制,來設定 ASP.NET Core 文化特性 cookie 的文化特性。 使用 MakeCookieValue 方法來建立 cookie。

CookieRequestCultureProvider DefaultCookieName 會傳回預設 cookie 名稱,以用來追蹤使用者的慣用文化特性資訊。 預設 cookie 名稱為 .AspNetCore.Culture

cookie 格式為 c=%LANGCODE%|uic=%LANGCODE%,其中 cCulture,而 uicUICulture,例如:

c=en-UK|uic=en-US

如果只提供其中一個文化特性資訊或 UI 文化特性,則提供的文化特性同時用於文化特性資訊和 UI 文化特性。

Accept-Language HTTP 標頭

您可在大多數的瀏覽器中設定 Accept-Language 標頭,其最初的設計目的是用來指定使用者的語言。 這項設定可指出瀏覽器已設好要傳送哪些項目,或已從基礎作業系統繼承哪些項目。 透過瀏覽器要求的 Accept-Language HTTP 標頭來偵測使用者的慣用語言,並非萬無一失 (請參閱 Setting language preferences in a browser (在瀏覽器中設定語言喜好設定)。 生產環境應用程式應該包含可讓使用者自訂文化特性的選擇方式。

在 Edge 中設定 Accept-Language HTTP 標頭

  1. 搜尋 [慣用語言] 的 [設定]

  2. 慣用語言會列在 [慣用語言] 方塊中。

  3. 選取 [新增語言] 以新增至清單。

  4. 選取語言旁的 [更多動作...],以變更喜好設定的順序。

Content-Language HTTP 標頭

Content-Language 實體標頭:

  • 用於描述針對適用對象的語言。
  • 允許使用者根據使用者自己慣用的語言來區分。

實體標頭用於 HTTP 要求和回應。

您可藉由設定 ApplyCurrentCultureToResponseHeaders 屬性來新增 Content-Language 標頭。

新增 Content-Language 標頭:

  • 允許 RequestLocalizationMiddleware 使用 CurrentUICulture 來設定 Content-Language 標頭。
  • 不需要明確設定回應標頭 Content-Language
app.UseRequestLocalization(new RequestLocalizationOptions
{
    ApplyCurrentCultureToResponseHeaders = true
});

套用 RouteDataRequest CultureProvider

RouteDataRequestCultureProvider 會根據 culture 路由值的值來設定文化特性。 如需下列項目的詳細資訊,請參閱使用中介軟體作為篩選的 URL 文化特性提供者

  • 使用中介軟體作為 ASP.NET Core 的篩選功能。
  • 如何使用 RouteDataRequestCultureProvider 從 URL 設定應用程式的文化特性。

如需如何全域套用 RouteDataRequestCultureProvider 的詳細資訊,請參閱使用中介軟體作為篩選全域套用 RouteDataRequest CultureProvider

使用自訂提供者

假設您想要讓客戶將他們的語言和文化特性儲存在您的資料庫中。 您可以撰寫提供者,以供使用者查詢這些值。 下列程式碼會示範如何新增自訂提供者:

private const string enUSCulture = "en-US";

services.Configure<RequestLocalizationOptions>(options =>
{
    var supportedCultures = new[]
    {
        new CultureInfo(enUSCulture),
        new CultureInfo("fr")
    };

    options.DefaultRequestCulture = new RequestCulture(culture: enUSCulture, uiCulture: enUSCulture);
    options.SupportedCultures = supportedCultures;
    options.SupportedUICultures = supportedCultures;

    options.AddInitialRequestCultureProvider(new CustomRequestCultureProvider(async context =>
    {
        // My custom request culture logic
        return await Task.FromResult(new ProviderCultureResult("en"));
    }));
});

使用 RequestLocalizationOptions 新增或移除當地語系化提供者。

變更要求文化特性提供者順序

RequestLocalizationOptions 有三個預設要求文化特性提供者:QueryStringRequestCultureProviderCookieRequestCultureProviderAcceptLanguageHeaderRequestCultureProvider。 使用 RequestLocalizationOptions.RequestCultureProviders 屬性來變更這些提供者的順序,如下所示:

    app.UseRequestLocalization(options =>
    {
        var questStringCultureProvider = options.RequestCultureProviders[0];    
        options.RequestCultureProviders.RemoveAt(0);
        options.RequestCultureProviders.Insert(1, questStringCultureProvider);
    });

在上述範例中,會切換 QueryStringRequestCultureProviderCookieRequestCultureProvider 的順序,因此 RequestLocalizationMiddleware 會先從 cookie 尋找文化特性,然後是查詢字串。

如先前所述,透過 AddInitialRequestCultureProvider 新增自訂提供者,以將順序設定為 0,因此此提供者的優先順序會高於其他提供者。

使用者覆寫文化特性

RequestLocalizationOptions.CultureInfoUseUserOverride 屬性可讓應用程式決定是否針對 CultureInfo DateTimeFormatNumberFormat 屬性使用非預設的 Windows 設定。 這不會對 Linux 造成任何影響。 這會直接對應至 UseUserOverride

    app.UseRequestLocalization(options =>
    {
        options.CultureInfoUseUserOverride = false;
    });

以程式設計方式來設定文化特性

GitHub 上的這個範例 Localization.StarterWeb 專案包含可設定 Culture 的 UI。 Views/Shared/_SelectLanguagePartial.cshtml 檔案可讓您從支援的文化特性清單中選取文化特性:

@using Microsoft.AspNetCore.Builder
@using Microsoft.AspNetCore.Http.Features
@using Microsoft.AspNetCore.Localization
@using Microsoft.AspNetCore.Mvc.Localization
@using Microsoft.Extensions.Options

@inject IViewLocalizer Localizer
@inject IOptions<RequestLocalizationOptions> LocOptions

@{
    var requestCulture = Context.Features.Get<IRequestCultureFeature>();
    var cultureItems = LocOptions.Value.SupportedUICultures
        .Select(c => new SelectListItem { Value = c.Name, Text = c.DisplayName })
        .ToList();
    var returnUrl = string.IsNullOrEmpty(Context.Request.Path) ? "~/" : $"~{Context.Request.Path.Value}";
}

<div title="@Localizer["Request culture provider:"] @requestCulture?.Provider?.GetType().Name">
    <form id="selectLanguage" asp-controller="Home" 
          asp-action="SetLanguage" asp-route-returnUrl="@returnUrl" 
          method="post" class="form-horizontal" role="form">
        <label asp-for="@requestCulture.RequestCulture.UICulture.Name">@Localizer["Language:"]</label> <select name="culture"
          onchange="this.form.submit();"
          asp-for="@requestCulture.RequestCulture.UICulture.Name" asp-items="cultureItems">
        </select>
    </form>
</div>

Views/Shared/_SelectLanguagePartial.cshtml 檔案會新增至 footer 版面配置檔案的 區段,以便將其供所有檢視使用:

<div class="container body-content" style="margin-top:60px">
    @RenderBody()
    <hr>
    <footer>
        <div class="row">
            <div class="col-md-6">
                <p>&copy; @System.DateTime.Now.Year - Localization</p>
            </div>
            <div class="col-md-6 text-right">
                @await Html.PartialAsync("_SelectLanguagePartial")
            </div>
        </div>
    </footer>
</div>

SetLanguage 方法會設定文化特性的 cookie。

[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);
}

您無法將 _SelectLanguagePartial.cshtml 插入此專案的範例程式碼。 GitHub 上的 Localization.StarterWeb 專案,其中的程式碼會部分透過相依性插入容器將 RequestLocalizationOptions 流向 Razor。

模型繫結會路由資料和查詢字串

請參閱模型繫結路由資料和查詢字串的全球化行為

下一步

當地語系化應用程式也涉及下列工作:

其他資源

Hisham Bin AteyaDamien BowdenBart Calixto, Nadeem AfanaRick Anderson

當地語系化應用程式的其中一項工作是實作策略,以針對應用程式傳回的每個回應選取適當的文化特性。

設定當地語系化中介軟體

您可以在當地語系化中介軟體中,設定要求目前的文化特性。 已在 Program.cs 中啟用當地語系化中介軟體。 您必須在可能檢查要求文化特性的任何中介軟體之前,設定當地語系化中介軟體 (例如 app.UseMvcWithDefaultRoute())。

builder.Services.Configure<RequestLocalizationOptions>(options =>
{
    var supportedCultures = new[] { "en-US", "fr" };
    options.SetDefaultCulture(supportedCultures[0])
        .AddSupportedCultures(supportedCultures)
        .AddSupportedUICultures(supportedCultures);
});

UseRequestLocalization 會初始化 RequestLocalizationOptions 物件。 在每次要求時,系統會列舉 RequestLocalizationOptions 中的 RequestCultureProvider 清單,並使用能成功判斷要求的文化特性的第一個提供者。 預設的提供者是來自 RequestLocalizationOptions 類別:

  1. QueryStringRequestCultureProvider
  2. CookieRequestCultureProvider
  3. AcceptLanguageHeaderRequestCultureProvider

預設清單會由針對性高到低來排列。 在本文稍後,您會了解如何變更順序,甚至新增自訂的文化特性提供者。 如果沒有任何提供者可以判斷要求的文化特性,即會使用 DefaultRequestCulture

QueryStringRequestCultureProvider

某些應用程式會使用查詢字串來設定 CultureInfo。 若是使用 cookie 或 Accept-Language 標頭方法的應用程式,您可以將查詢字串新增至 URL 以偵錯和測試程式碼。 系統預設會將 QueryStringRequestCultureProvider 登錄為 RequestCultureProvider 清單中的第一個當地語系化提供者。 您應傳遞查詢字串參數 cultureui-culture。 下列範例會設定西班牙文/墨西哥的特定文化特性 (語言和地區):

http://localhost:5000/?culture=es-MX&ui-culture=es-MX

如果只傳入 cultureui-culture,則查詢字串提供者會使用傳入的值來設定這兩個值。 例如,若只設定文化特性,即會同時設定 CultureUICulture

http://localhost:5000/?culture=es-MX

CookieRequestCultureProvider

生產環境應用程式通常會提供一個機制,來設定 ASP.NET Core 文化特性 cookie 的文化特性。 使用 MakeCookieValue 方法來建立 cookie。

xref:Microsoft.AspNetCore.Localization.CookieRequestCultureProvider>DefaultCookieName 會傳回用於追蹤使用者慣用文化特性資訊的預設 cookie 名稱。 預設 cookie 名稱為 .AspNetCore.Culture

cookie 格式為 c=%LANGCODE%|uic=%LANGCODE%,其中 cCulture,而 uicUICulture,例如:

c=en-UK|uic=en-US

如果只提供其中一個文化特性資訊或 UI 文化特性,則提供的文化特性同時用於文化特性資訊和 UI 文化特性。

Accept-Language HTTP 標頭

您可在大多數的瀏覽器中設定 Accept-Language 標頭,其最初的設計目的是用來指定使用者的語言。 這項設定可指出瀏覽器已設好要傳送哪些項目,或已從基礎作業系統繼承哪些項目。 透過瀏覽器要求的 Accept-Language HTTP 標頭來偵測使用者的慣用語言,並非萬無一失 (請參閱 Setting language preferences in a browser (在瀏覽器中設定語言喜好設定)。 生產環境應用程式應該包含可讓使用者自訂文化特性的選擇方式。

在 Edge 中設定 Accept-Language HTTP 標頭

  1. 搜尋 [慣用語言] 的 [設定]

  2. 慣用語言會列在 [慣用語言] 方塊中。

  3. 選取 [新增語言] 以新增至清單。

  4. 選取語言旁的 [更多動作...],以變更喜好設定的順序。

Content-Language HTTP 標頭

Content-Language 實體標頭:

  • 用於描述針對適用對象的語言。
  • 允許使用者根據使用者自己慣用的語言來區分。

實體標頭用於 HTTP 要求和回應。

您可藉由設定 ApplyCurrentCultureToResponseHeaders 屬性來新增 Content-Language 標頭。

新增 Content-Language 標頭:

  • 允許 RequestLocalizationMiddleware 使用 CurrentUICulture 來設定 Content-Language 標頭。
  • 不需要明確設定回應標頭 Content-Language
app.UseRequestLocalization(new RequestLocalizationOptions
{
    ApplyCurrentCultureToResponseHeaders = true
});

使用自訂提供者

假設您想要讓客戶將他們的語言和文化特性儲存在您的資料庫中。 您可以撰寫提供者,以供使用者查詢這些值。 下列程式碼會示範如何新增自訂提供者:

private const string enUSCulture = "en-US";

services.Configure<RequestLocalizationOptions>(options =>
{
    var supportedCultures = new[]
    {
        new CultureInfo(enUSCulture),
        new CultureInfo("fr")
    };

    options.DefaultRequestCulture = new RequestCulture(culture: enUSCulture, uiCulture: enUSCulture);
    options.SupportedCultures = supportedCultures;
    options.SupportedUICultures = supportedCultures;

    options.AddInitialRequestCultureProvider(new CustomRequestCultureProvider(async context =>
    {
        // My custom request culture logic
        return await Task.FromResult(new ProviderCultureResult("en"));
    }));
});

使用 RequestLocalizationOptions 新增或移除當地語系化提供者。

變更要求文化特性提供者順序

RequestLocalizationOptions 有三個預設要求文化特性提供者:QueryStringRequestCultureProviderCookieRequestCultureProviderAcceptLanguageHeaderRequestCultureProvider。 使用 RequestLocalizationOptions.RequestCultureProviders 屬性來變更這些提供者的順序,如下所示:

    app.UseRequestLocalization(options =>
    {
        var questStringCultureProvider = options.RequestCultureProviders[0];    
        options.RequestCultureProviders.RemoveAt(0);
        options.RequestCultureProviders.Insert(1, questStringCultureProvider);
    });

在上述範例中,會切換 QueryStringRequestCultureProviderCookieRequestCultureProvider 的順序,因此 RequestLocalizationMiddleware 會先從 cookie 尋找文化特性,然後是查詢字串。

如先前所述,透過 AddInitialRequestCultureProvider 新增自訂提供者,以將順序設定為 0,因此此提供者的優先順序會高於其他提供者。

以程式設計方式來設定文化特性

GitHub 上的這個範例 Localization.StarterWeb 專案包含可設定 Culture 的 UI。 Views/Shared/_SelectLanguagePartial.cshtml 檔案可讓您從支援的文化特性清單中選取文化特性:

@using Microsoft.AspNetCore.Builder
@using Microsoft.AspNetCore.Http.Features
@using Microsoft.AspNetCore.Localization
@using Microsoft.AspNetCore.Mvc.Localization
@using Microsoft.Extensions.Options

@inject IViewLocalizer Localizer
@inject IOptions<RequestLocalizationOptions> LocOptions

@{
    var requestCulture = Context.Features.Get<IRequestCultureFeature>();
    var cultureItems = LocOptions.Value.SupportedUICultures
        .Select(c => new SelectListItem { Value = c.Name, Text = c.DisplayName })
        .ToList();
    var returnUrl = string.IsNullOrEmpty(Context.Request.Path) ? "~/" : $"~{Context.Request.Path.Value}";
}

<div title="@Localizer["Request culture provider:"] @requestCulture?.Provider?.GetType().Name">
    <form id="selectLanguage" asp-controller="Home" 
          asp-action="SetLanguage" asp-route-returnUrl="@returnUrl" 
          method="post" class="form-horizontal" role="form">
        <label asp-for="@requestCulture.RequestCulture.UICulture.Name">@Localizer["Language:"]</label> <select name="culture"
          onchange="this.form.submit();"
          asp-for="@requestCulture.RequestCulture.UICulture.Name" asp-items="cultureItems">
        </select>
    </form>
</div>

Views/Shared/_SelectLanguagePartial.cshtml 檔案會新增至 footer 版面配置檔案的 區段,以便將其供所有檢視使用:

<div class="container body-content" style="margin-top:60px">
    @RenderBody()
    <hr>
    <footer>
        <div class="row">
            <div class="col-md-6">
                <p>&copy; @System.DateTime.Now.Year - Localization</p>
            </div>
            <div class="col-md-6 text-right">
                @await Html.PartialAsync("_SelectLanguagePartial")
            </div>
        </div>
    </footer>
</div>

SetLanguage 方法會設定文化特性的 cookie。

[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);
}

您無法將 _SelectLanguagePartial.cshtml 插入此專案的範例程式碼。 GitHub 上的 Localization.StarterWeb 專案,其中的程式碼會部分透過相依性插入容器將 RequestLocalizationOptions 流向 Razor。

模型繫結會路由資料和查詢字串

請參閱模型繫結路由資料和查詢字串的全球化行為

下一步

當地語系化應用程式也涉及下列工作:

其他資源

Rick AndersonDamien BowdenBart CalixtoNadeem AfanaHisham Bin Ateya 提供

當地語系化應用程式的其中一項工作是實作策略,以針對應用程式傳回的每個回應選取適當的文化特性。

設定當地語系化中介軟體

您可以在當地語系化中介軟體中,設定要求目前的文化特性。 已在 Startup.Configure 方法中啟用當地語系化中介軟體。 您必須在可能檢查要求文化特性的任何中介軟體之前,設定當地語系化中介軟體 (例如 app.UseMvcWithDefaultRoute())。

var supportedCultures = new[] { "en-US", "fr" };
var localizationOptions = new RequestLocalizationOptions().SetDefaultCulture(supportedCultures[0])
    .AddSupportedCultures(supportedCultures)
    .AddSupportedUICultures(supportedCultures);

app.UseRequestLocalization(localizationOptions);

UseRequestLocalization 會初始化 RequestLocalizationOptions 物件。 在每次要求時,系統會列舉 RequestLocalizationOptions 中的 RequestCultureProvider 清單,並使用能成功判斷要求的文化特性的第一個提供者。 預設的提供者是來自 RequestLocalizationOptions 類別:

  1. QueryStringRequestCultureProvider
  2. CookieRequestCultureProvider
  3. AcceptLanguageHeaderRequestCultureProvider

預設清單會由針對性高到低來排列。 在本文稍後,您會了解如何變更順序,甚至新增自訂的文化特性提供者。 如果沒有任何提供者可以判斷要求的文化特性,即會使用 DefaultRequestCulture

QueryStringRequestCultureProvider

某些應用程式會使用查詢字串來設定 CultureInfo。 若是使用 cookie 或 Accept-Language 標頭方法的應用程式,您可以將查詢字串新增至 URL 以偵錯和測試程式碼。 系統預設會將 QueryStringRequestCultureProvider 登錄為 RequestCultureProvider 清單中的第一個當地語系化提供者。 您應傳遞查詢字串參數 cultureui-culture。 下列範例會設定西班牙文/墨西哥的特定文化特性 (語言和地區):

http://localhost:5000/?culture=es-MX&ui-culture=es-MX

如果您只傳入兩者其一 (cultureui-culture),查詢字串提供者就會使用您傳入的項目來設定這兩個值。 例如,若只設定文化特性,即會同時設定 CultureUICulture

http://localhost:5000/?culture=es-MX

CookieRequestCultureProvider

生產環境應用程式通常會提供一個機制,來設定 ASP.NET Core 文化特性 cookie 的文化特性。 使用 MakeCookieValue 方法來建立 cookie。

CookieRequestCultureProvider DefaultCookieName 會傳回預設 cookie 名稱,以用來追蹤使用者的慣用文化特性資訊。 預設 cookie 名稱為 .AspNetCore.Culture

cookie 格式為 c=%LANGCODE%|uic=%LANGCODE%,其中 cCulture,而 uicUICulture,例如:

c=en-UK|uic=en-US

如果您只指定文化特性資訊和 UI 文化特性其一,系統就會將您所指定的文化特性用於文化特性資訊和 UI 文化特性。

Accept-Language HTTP 標頭

您可在大多數的瀏覽器中設定 Accept-Language 標頭,其最初的設計目的是用來指定使用者的語言。 這項設定可指出瀏覽器已設好要傳送哪些項目,或已從基礎作業系統繼承哪些項目。 透過瀏覽器要求的 Accept-Language HTTP 標頭來偵測使用者的慣用語言,並非萬無一失 (請參閱 Setting language preferences in a browser (在瀏覽器中設定語言喜好設定)。 生產環境應用程式應該包含可讓使用者自訂文化特性的選擇方式。

在 Edge 中設定 Accept-Language HTTP 標頭

  1. 搜尋 [慣用語言] 的 [設定]

  2. 慣用語言會列在 [慣用語言] 方塊中。

  3. 選取 [新增語言] 以新增至清單。

  4. 選取語言旁的 [更多動作...],以變更喜好設定的順序。

Content-Language HTTP 標頭

Content-Language 實體標頭:

  • 用於描述針對適用對象的語言。
  • 允許使用者根據使用者自己慣用的語言來區分。

實體標頭用於 HTTP 要求和回應。

您可藉由設定 ApplyCurrentCultureToResponseHeaders 屬性來新增 Content-Language 標頭。

新增 Content-Language 標頭:

  • 允許 RequestLocalizationMiddleware 使用 CurrentUICulture 來設定 Content-Language 標頭。
  • 不需要明確設定回應標頭 Content-Language
app.UseRequestLocalization(new RequestLocalizationOptions
{
    ApplyCurrentCultureToResponseHeaders = true
});

使用自訂提供者

假設您想要讓客戶將他們的語言和文化特性儲存在您的資料庫中。 您可以撰寫提供者,以供使用者查詢這些值。 下列程式碼會示範如何新增自訂提供者:

private const string enUSCulture = "en-US";

services.Configure<RequestLocalizationOptions>(options =>
{
    var supportedCultures = new[]
    {
        new CultureInfo(enUSCulture),
        new CultureInfo("fr")
    };

    options.DefaultRequestCulture = new RequestCulture(culture: enUSCulture, uiCulture: enUSCulture);
    options.SupportedCultures = supportedCultures;
    options.SupportedUICultures = supportedCultures;

    options.AddInitialRequestCultureProvider(new CustomRequestCultureProvider(async context =>
    {
        // My custom request culture logic
        return await Task.FromResult(new ProviderCultureResult("en"));
    }));
});

使用 RequestLocalizationOptions 新增或移除當地語系化提供者。

變更要求文化特性提供者順序

RequestLocalizationOptions 有三個預設要求文化特性提供者:QueryStringRequestCultureProviderCookieRequestCultureProviderAcceptLanguageHeaderRequestCultureProvider。 使用 RequestLocalizationOptions.RequestCultureProviders 屬性來變更這些提供者的順序,如下所示:

    app.UseRequestLocalization(options =>
    {
        var questStringCultureProvider = options.RequestCultureProviders[0];    
        options.RequestCultureProviders.RemoveAt(0);
        options.RequestCultureProviders.Insert(1, questStringCultureProvider);
    });

在上述範例中,會切換 QueryStringRequestCultureProviderCookieRequestCultureProvider 的順序,因此 RequestLocalizationMiddleware 會先從 cookie 尋找文化特性,然後是查詢字串。

如先前所述,透過 AddInitialRequestCultureProvider 新增自訂提供者,以將順序設定為 0,因此此提供者的優先順序會高於其他提供者。

以程式設計方式來設定文化特性

GitHub 上的這個範例 Localization.StarterWeb 專案包含可設定 Culture 的 UI。 Views/Shared/_SelectLanguagePartial.cshtml 檔案可讓您從支援的文化特性清單中選取文化特性:

@using Microsoft.AspNetCore.Builder
@using Microsoft.AspNetCore.Http.Features
@using Microsoft.AspNetCore.Localization
@using Microsoft.AspNetCore.Mvc.Localization
@using Microsoft.Extensions.Options

@inject IViewLocalizer Localizer
@inject IOptions<RequestLocalizationOptions> LocOptions

@{
    var requestCulture = Context.Features.Get<IRequestCultureFeature>();
    var cultureItems = LocOptions.Value.SupportedUICultures
        .Select(c => new SelectListItem { Value = c.Name, Text = c.DisplayName })
        .ToList();
    var returnUrl = string.IsNullOrEmpty(Context.Request.Path) ? "~/" : $"~{Context.Request.Path.Value}";
}

<div title="@Localizer["Request culture provider:"] @requestCulture?.Provider?.GetType().Name">
    <form id="selectLanguage" asp-controller="Home" 
          asp-action="SetLanguage" asp-route-returnUrl="@returnUrl" 
          method="post" class="form-horizontal" role="form">
        <label asp-for="@requestCulture.RequestCulture.UICulture.Name">@Localizer["Language:"]</label> <select name="culture"
          onchange="this.form.submit();"
          asp-for="@requestCulture.RequestCulture.UICulture.Name" asp-items="cultureItems">
        </select>
    </form>
</div>

Views/Shared/_SelectLanguagePartial.cshtml 檔案會新增至 footer 版面配置檔案的 區段,以便將其供所有檢視使用:

<div class="container body-content" style="margin-top:60px">
    @RenderBody()
    <hr>
    <footer>
        <div class="row">
            <div class="col-md-6">
                <p>&copy; @System.DateTime.Now.Year - Localization</p>
            </div>
            <div class="col-md-6 text-right">
                @await Html.PartialAsync("_SelectLanguagePartial")
            </div>
        </div>
    </footer>
</div>

SetLanguage 方法會設定文化特性的 cookie。

[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);
}

您無法將 _SelectLanguagePartial.cshtml 插入此專案的範例程式碼。 GitHub 上的 Localization.StarterWeb 專案,其中的程式碼會部分透過相依性插入容器將 RequestLocalizationOptions 流向 Razor。

模型繫結會路由資料和查詢字串

請參閱模型繫結路由資料和查詢字串的全球化行為

下一步

當地語系化應用程式也涉及下列工作:

其他資源