ローカライズされた ASP.NET Core アプリで要求ごとに言語またはカルチャを選択する戦略を実装する

Hisham Bin Ateya、Damien Bowden、Bart Calixto、Nadeem Afana、Rick Anderson

アプリをローカライズするためのタスクの 1 つは、アプリが返す応答ごとに適切なカルチャを選択するための戦略を実装することです。

ローカライズ ミドルウェアを構成する

要求時に現在のカルチャが、ローカリゼーション ミドルウェアで設定されます。 ローカリゼーション ミドルウェアは、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 リストの最初のローカリゼーション プロバイダーとして登録されます。 クエリ文字列パラメーター culture と ui-culture を渡します。 次の例では、特定のカルチャ (言語および地域) をスペイン語/メキシコに設定します。

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

culture または ui-culture のみが渡された場合、クエリ文字列プロバイダーは、渡された値を使用して両方の値を設定します。 たとえば、カルチャだけを設定すると、Culture と UICulture の両方が設定されます。

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

CookieRequestCultureProvider

多くの場合、実稼働アプリケーションは、ASP.NET Core カルチャ cookie を使用してカルチャを設定するためのメカニズムを提供します。 cookie を作成するには、MakeCookieValue メソッドを使用します。

CookieRequestCultureProviderDefaultCookieName は、ユーザーの優先するカルチャ情報を追跡するために使用される既定の cookie 名を返します。 既定の cookie 名は .AspNetCore.Culture です。

cookie の形式は c=%LANGCODE%|uic=%LANGCODE% です。ここで、c は Culture であり、uic は UICulture です。たとえば、次のようになります。

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 culture provider using middleware as filters」 (ミドルウェアをフィルターとして使用する URL カルチャ プロバイダー) を参照してください。

• ミドルウェアを ASP.NET Core のフィルター機能として使用する。
• RouteDataRequestCultureProvider を使用して、URL からアプリのカルチャを設定する方法。

RouteDataRequestCultureProvider をグローバルに適用する方法については、「Applying the RouteDataRequest CultureProvider globally with middleware as filters」 (ミドルウェアをフィルターとして使用して 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 の既定の要求カルチャ プロバイダーは次の 3 つです: QueryStringRequestCultureProvider、CookieRequestCultureProvider、AcceptLanguageHeaderRequestCultureProvider。 次に示すように、RequestLocalizationOptions.RequestCultureProviders プロパティを使用して、これらのプロバイダーの順序を変更できます。

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

上の例では、QueryStringRequestCultureProvider と CookieRequestCultureProvider の順序を入れ替えているので、RequestLocalizationMiddleware は最初に cookie からカルチャを探し、次にクエリ文字列から探します。

前述のように、AddInitialRequestCultureProvider を使用してカスタム プロバイダーを追加します。このプロバイダーは、順序を 0 に設定しているので、他のプロバイダーよりも優先されます。

ユーザー オーバーライド カルチャ

RequestLocalizationOptions.CultureInfoUseUserOverride プロパティを使用すると、CultureInfoDateTimeFormat プロパティと NumberFormat プロパティに既定以外の 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 プロジェクトには、依存関係の挿入コンテナーを介して Razor 部分に RequestLocalizationOptions をフローするコードがあります。

モデル バインド ルート データとクエリ文字列

「モデル バインド ルート データとクエリ文字列のグローバリゼーション動作」を参照してください。

次のステップ

アプリのローカライズには、次のタスクも含まれます。

• アプリのコンテンツをローカライズ可能にする。
• アプリでサポートする言語およびカルチャ用にローカライズされたリソースを提供する

その他のリソース

• ASP.NET Core でミドルウェアをフィルターとして使用する URL カルチャ プロバイダー
• ミドルウェアをフィルターとして使用して RouteDataRequest CultureProvider をグローバルに適用する
• ASP.NET Core のグローバリゼーションおよびローカリゼーション
• ASP.NET Core アプリのコンテンツをローカライズ可能にする
• ASP.NET Core アプリで言語とカルチャ用にローカライズされたリソースを提供する
• ASP.NET Core のローカライズに関するトラブルシューティング
• .NET アプリケーションのグローバライズとローカライズ
• 記事で使用されている Localization.StarterWeb プロジェクト。
• .resx ファイル内のリソース
• Microsoft 多言語アプリ ツールキット
• ローカリゼーションとジェネリック