ASP.NET Core のグローバリゼーションおよびローカリゼーションGlobalization and localization in ASP.NET Core

作成者: Rick AndersonDamien BowdenBart CalixtoNadeem AfanaHisham Bin AteyaBy Rick Anderson, Damien Bowden, Bart Calixto, Nadeem Afana, and Hisham Bin Ateya

ASP.NET Core で多言語の Web サイトを作成すると、より幅広い対象者がサイトにアクセスできるようになります。Creating a multilingual website with ASP.NET Core will allow your site to reach a wider audience. ASP.NET Core は、さまざまな言語と文化にローカライズするためのサービスとミドルウェアを提供します。ASP.NET Core provides services and middleware for localizing into different languages and cultures.

国際化には、グローバリゼーションローカリゼーションが含まれます。Internationalization involves Globalization and Localization. グローバリゼーションとは異なるカルチャをサポートするアプリを設計するプロセスです。Globalization is the process of designing apps that support different cultures. グローバリゼーションによって、特定の地域に関連する定義済みの言語セットの入出力と表示のサポートが追加されます。Globalization adds support for input, display, and output of a defined set of language scripts that relate to specific geographic areas.

ローカリゼーションとは、ローカライズのために既に処理されているグローバル化されたアプリを特定のカルチャ/ロケールに適合させるプロセスです。Localization is the process of adapting a globalized app, which you have already processed for localizability, to a particular culture/locale. 詳細については、本ドキュメントの末尾にある「グローバリゼーションとローカリゼーションの用語」を参照してください。For more information see Globalization and localization terms near the end of this document.

アプリのローカリゼーションには、以下のものが関与します。App localization involves the following:

  1. アプリのコンテンツをローカライズできるようにするMake the app's content localizable

  2. サポートする言語およびカルチャのローカライズされたリソースを提供するProvide localized resources for the languages and cultures you support

  3. 要求ごとに言語/カルチャを選択するための戦略を実装するImplement a strategy to select the language/culture for each request

アプリのコンテンツをローカライズできるようにするMake the app's content localizable

ASP.NET Core で導入された IStringLocalizerIStringLocalizer<T> は、ローカライズされたアプリの開発時に生産性を向上させるように設計されています。Introduced in ASP.NET Core, IStringLocalizer and IStringLocalizer<T> were architected to improve productivity when developing localized apps. IStringLocalizer は、ResourceManagerResourceReader を使用して、実行時にカルチャ固有のリソースを提供します。IStringLocalizer uses the ResourceManager and ResourceReader to provide culture-specific resources at run time. シンプルなインターフェイスには、ローカライズされた文字列を返すためのインデクサーと IEnumerable があります。The simple interface has an indexer and an IEnumerable for returning localized strings. IStringLocalizer では、リソース ファイルに既定の言語文字列を格納する必要がありません。IStringLocalizer doesn't require you to store the default language strings in a resource file. ローカリゼーションの対象となるアプリを開発することができ、開発の早い段階でリソース ファイルを作成する必要はありません。You can develop an app targeted for localization and not need to create resource files early in development. 次のコードは、ローカリゼーションのために文字列 "About Title" をラップする方法を示しています。The code below shows how to wrap the string "About Title" for localization.

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

namespace Localization.StarterWeb.Controllers
{
    [Route("api/[controller]")]
    public class AboutController : Controller
    {
        private readonly IStringLocalizer<AboutController> _localizer;

        public AboutController(IStringLocalizer<AboutController> localizer)
        {
            _localizer = localizer;
        }

        [HttpGet]
        public string Get()
        {
            return _localizer["About Title"];
        }
    }
}

上記のコードで、IStringLocalizer<T> の実装は、依存関係の挿入によって実行されます。In the code above, the IStringLocalizer<T> implementation comes from Dependency Injection. "About Title" のローカライズされた値が見つからない場合、インデクサーのキー、つまり文字列 "About Title" が返されます。If the localized value of "About Title" isn't found, then the indexer key is returned, that is, the string "About Title". アプリで、既定の言語のリテラル文字列をそのままにし、ローカライザーにそれらをラップすることができるので、アプリの開発に専念することができます。You can leave the default language literal strings in the app and wrap them in the localizer, so that you can focus on developing the app. 既定の言語でアプリを開発し、既定のリソース ファイルを最初に作成せずに、ローカリゼーション手順用に準備します。You develop your app with your default language and prepare it for the localization step without first creating a default resource file. または、従来のアプローチを使用し、既定の言語文字列を取得するキーを提供できます。Alternatively, you can use the traditional approach and provide a key to retrieve the default language string. 既定の言語の .resx ファイルを使用せずに、文字列リテラルをラップするだけの新しいワークフローは、多くの開発者にとって、アプリをローカライズする際のオーバーヘッドの削減になります。For many developers the new workflow of not having a default language .resx file and simply wrapping the string literals can reduce the overhead of localizing an app. 他の開発者は、長い文字列リテラルの操作が容易で、ローカライズされた文字列を更新しやすい従来のワークフローを好みます。Other developers will prefer the traditional work flow as it can make it easier to work with longer string literals and make it easier to update localized strings.

HTML を格納しているリソースには、IHtmlLocalizer<T> の実装を使用します。Use the IHtmlLocalizer<T> implementation for resources that contain HTML. IHtmlLocalizer HTML は、リソース文字列でフォーマットされた引数をエンコードしますが、リソース文字列自体は HTML エンコードしません。IHtmlLocalizer HTML encodes arguments that are formatted in the resource string, but doesn't HTML encode the resource string itself. 下の強調表示されたサンプルでは、name パラメーターの値のみが HTML エンコードされます。In the sample highlighted below, only the value of name parameter is HTML encoded.

using System;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Localization;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Localization;

namespace Localization.StarterWeb.Controllers
{
    public class BookController : Controller
    {
        private readonly IHtmlLocalizer<BookController> _localizer;

        public BookController(IHtmlLocalizer<BookController> localizer)
        {
            _localizer = localizer;
        }

        public IActionResult Hello(string name)
        {
            ViewData["Message"] = _localizer["<b>Hello</b><i> {0}</i>", name];

            return View();
        }

注: 一般的に、HTML ではなく、テキストのみをローカライズする必要があります。Note: You generally want to only localize text and not HTML.

最下位のレベルでは、依存関係の挿入から IStringLocalizerFactory を取得できます。At the lowest level, you can get IStringLocalizerFactory out of Dependency Injection:

{
    public class TestController : Controller
    {
        private readonly IStringLocalizer _localizer;
        private readonly IStringLocalizer _localizer2;

        public TestController(IStringLocalizerFactory factory)
        {
            var type = typeof(SharedResource);
            var assemblyName = new AssemblyName(type.GetTypeInfo().Assembly.FullName);
            _localizer = factory.Create(type);
            _localizer2 = factory.Create("SharedResource", assemblyName.Name);
        }       

        public IActionResult About()
        {
            ViewData["Message"] = _localizer["Your application description page."] 
                + " loc 2: " + _localizer2["Your application description page."];

上記のコードは、2 つの各ファクトリ作成メソッドを示しています。The code above demonstrates each of the two factory create methods.

ローカライズされた文字列は、コントローラーまたは領域で仕切るか、1 つのコンテナーにすることができます。You can partition your localized strings by controller, area, or have just one container. サンプル アプリでは、共有されるリソースのために SharedResource というダミー クラスを使用しています。In the sample app, a dummy class named SharedResource is used for shared resources.

// Dummy class to group shared resources

namespace Localization.StarterWeb
{
    public class SharedResource
    {
    }
}

一部の開発者は、Startup クラスを使用してグローバル文字列または共有文字列を格納します。Some developers use the Startup class to contain global or shared strings. 下のサンプルでは、InfoControllerSharedResource のローカライザーが使用されています。In the sample below, the InfoController and the SharedResource localizers are used:

public class InfoController : Controller
{
    private readonly IStringLocalizer<InfoController> _localizer;
    private readonly IStringLocalizer<SharedResource> _sharedLocalizer;

    public InfoController(IStringLocalizer<InfoController> localizer,
                   IStringLocalizer<SharedResource> sharedLocalizer)
    {
        _localizer = localizer;
        _sharedLocalizer = sharedLocalizer;
    }

    public string TestLoc()
    {
        string msg = "Shared resx: " + _sharedLocalizer["Hello!"] +
                     " Info resx " + _localizer["Hello!"];
        return msg;
    }

ビューのローカリゼーションView localization

IViewLocalizer サービスは、ビューのローカライズされた文字列を提供します。The IViewLocalizer service provides localized strings for a view. ViewLocalizer クラスは、このインターフェイスを実装し、ビューのファイル パスからリソースの場所を見つけます。The ViewLocalizer class implements this interface and finds the resource location from the view file path. 次のコードは、IViewLocalizer の既定の実装の使用方法を示しています。The following code shows how to use the default implementation of IViewLocalizer:

@using Microsoft.AspNetCore.Mvc.Localization

@inject IViewLocalizer Localizer

@{
    ViewData["Title"] = Localizer["About"];
}
<h2>@ViewData["Title"].</h2>
<h3>@ViewData["Message"]</h3>

<p>@Localizer["Use this area to provide additional information."]</p>

IViewLocalizer の既定の実装は、ビューのファイル名に基づいてリソース ファイルを見つけます。The default implementation of IViewLocalizer finds the resource file based on the view's file name. グローバルな共有リソース ファイルを使用するオプションはありません。There's no option to use a global shared resource file. ViewLocalizer は、IHtmlLocalizer を使用してローカライザーを実装するので、Razor は、ローカライズされた文字列を HTML エンコードしません。ViewLocalizer implements the localizer using IHtmlLocalizer, so Razor doesn't HTML encode the localized string. リソース文字列をパラメーター化することができます。IViewLocalizer は、パラメーターを HTML エンコードしますが、リソース文字列は HTML エンコードしません。You can parameterize resource strings and IViewLocalizer will HTML encode the parameters, but not the resource string. 次の Razor マークアップについて考えます。Consider the following Razor markup:

@Localizer["<i>Hello</i> <b>{0}!</b>", UserManager.GetUserName(User)]

フランス語のリソース ファイルには次の値が含まれます。A French resource file could contain the following:

キーKey [値]Value
<i>Hello</i> <b>{0}!</b> <i>Bonjour</i> <b>{0} !</b>

描画されたビューには、リソース ファイルからの HTML マークアップが含まれます。The rendered view would contain the HTML markup from the resource file.

注: 一般的に、HTML ではなく、テキストのみをローカライズする必要があります。Note: You generally want to only localize text and not HTML.

ビュー内の共有リソース ファイルを使用するには、IHtmlLocalizer<T> を挿入します。To use a shared resource file in a view, inject IHtmlLocalizer<T>:

@using Microsoft.AspNetCore.Mvc.Localization
@using Localization.StarterWeb.Services

@inject IViewLocalizer Localizer
@inject IHtmlLocalizer<SharedResource> SharedLocalizer

@{
    ViewData["Title"] = Localizer["About"];
}
<h2>@ViewData["Title"].</h2>

<h1>@SharedLocalizer["Hello!"]</h1>

DataAnnotations のローカリゼーションDataAnnotations localization

DataAnnotations エラー メッセージは IStringLocalizer<T> を使用してローカライズします。DataAnnotations error messages are localized with IStringLocalizer<T>. オプション ResourcesPath = "Resources" を使用して、RegisterViewModel のエラー メッセージを次のいずれかのパスに格納できます。Using the option ResourcesPath = "Resources", the error messages in RegisterViewModel can be stored in either of the following paths:

  • Resources/ViewModels.Account.RegisterViewModel.fr.resxResources/ViewModels.Account.RegisterViewModel.fr.resx
  • Resources/ViewModels/Account/RegisterViewModel.fr.resxResources/ViewModels/Account/RegisterViewModel.fr.resx
public class RegisterViewModel
{
    [Required(ErrorMessage = "The Email field is required.")]
    [EmailAddress(ErrorMessage = "The Email field is not a valid email address.")]
    [Display(Name = "Email")]
    public string Email { get; set; }

    [Required(ErrorMessage = "The Password field is required.")]
    [StringLength(8, ErrorMessage = "The {0} must be at least {2} characters long.", MinimumLength = 6)]
    [DataType(DataType.Password)]
    [Display(Name = "Password")]
    public string Password { get; set; }

    [DataType(DataType.Password)]
    [Display(Name = "Confirm password")]
    [Compare("Password", ErrorMessage = "The password and confirmation password do not match.")]
    public string ConfirmPassword { get; set; }
}

ASP.NET Core MVC 1.1.0 以上では、非検証属性がローカライズされます。In ASP.NET Core MVC 1.1.0 and higher, non-validation attributes are localized. ASP.NET Core MVC 1.0 は、非検証属性のローカライズされた文字列を検索しませんASP.NET Core MVC 1.0 does not look up localized strings for non-validation attributes.

複数のクラスに 1 つのリソース文字列を使用するUsing one resource string for multiple classes

次のコードは、複数のクラスに検証属性の 1 つのリソース文字列を使用する方法を示しています。The following code shows how to use one resource string for validation attributes with multiple classes:

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc()
        .AddDataAnnotationsLocalization(options => {
            options.DataAnnotationLocalizerProvider = (type, factory) =>
                factory.Create(typeof(SharedResource));
        });
}

上記のコードでは、SharedResource は、resx に対応するクラスであり、ここに検証メッセージが格納されます。In the preceeding code, SharedResource is the class corresponding to the resx where your validation messages are stored. この方法では、DataAnnotations は、各クラスのリソースではなく、SharedResource のみを使用します。With this approach, DataAnnotations will only use SharedResource, rather than the resource for each class.

サポートする言語およびカルチャのローカライズされたリソースを提供するProvide localized resources for the languages and cultures you support

SupportedCultures と SupportedUICulturesSupportedCultures and SupportedUICultures

ASP.NET Core では、SupportedCulturesSupportedUICultures という 2 つのカルチャ値を指定できます。ASP.NET Core allows you to specify two culture values, SupportedCultures and SupportedUICultures. 日付、数値、および通貨の書式設定など、カルチャに依存する関数の結果は、SupportedCulturesCultureInfo オブジェクトによって決まります。The CultureInfo object for SupportedCultures determines the results of culture-dependent functions, such as date, time, number, and currency formatting. テキストの並べ替え順序、大文字と小文字の表記規則、文字列比較も SupportedCultures によって決まります。SupportedCultures also determines the sorting order of text, casing conventions, and string comparisons. サーバーがカルチャを取得する方法の詳細については、「CultureInfo.CurrentCulture」を参照してください。See CultureInfo.CurrentCulture for more info on how the server gets the Culture. SupportedUICultures は、.resx ファイルからのどの翻訳文字列が ResourceManager によって検索されるかを決定します。The SupportedUICultures determines which translates strings (from .resx files) are looked up by the ResourceManager. ResourceManager は、CurrentUICulture によって決定されるカルチャ固有の文字列を単に検索します。The ResourceManager simply looks up culture-specific strings that's determined by CurrentUICulture. .NET のすべてのスレッドに CurrentCulture オブジェクトと CurrentUICultureオブジェクトがあります。Every thread in .NET has CurrentCulture and CurrentUICulture objects. ASP.NET Core は、カルチャに依存する関数を表示するときに、これらの値を検査します。ASP.NET Core inspects these values when rendering culture-dependent functions. たとえば、現在のスレッドのカルチャが "en-US" (英語、米国) に設定されている場合は、DateTime.Now.ToLongDateString() は、"Thursday, February 18, 2016" を表示しますが、CurrentCulture が "es-ES" (スペイン語、スペイン) に設定されている場合、出力は "jueves, 18 de febrero de 2016" になります。For example, if the current thread's culture is set to "en-US" (English, United States), DateTime.Now.ToLongDateString() displays "Thursday, February 18, 2016", but if CurrentCulture is set to "es-ES" (Spanish, Spain) the output will be "jueves, 18 de febrero de 2016".

リソース ファイルResource files

リソース ファイルは、ローカライズ可能な文字列をコードから分離するために役立つメカニズムです。A resource file is a useful mechanism for separating localizable strings from code. 既定以外の言語の翻訳された文字列は、分離された .resx リソース ファイルです。Translated strings for the non-default language are isolated .resx resource files. たとえば、翻訳された文字列を含む Welcome.es.resx という名前のスペイン語のリソース ファイルを作成したい場合があります。For example, you might want to create Spanish resource file named Welcome.es.resx containing translated strings. "es" は、スペイン語の言語コードです。"es" is the language code for Spanish. Visual Studio でこのリソース ファイルを作成するには、次の手順を実行します。To create this resource file in Visual Studio:

  1. ソリューション エクスプローラーで、リソース ファイルが格納されているフォルダーを右クリックし、[追加] > [新しい項目] を選択します。In Solution Explorer, right click on the folder which will contain the resource file > Add > New Item.

    入れ子になったコンテキスト メニュー: ソリューション エクスプローラーでリソースのコンテキスト メニューが開かれます。

  2. インストールされているテンプレートの検索ボックスに、「resource」と入力し、ファイルに名前を付けます。In the Search installed templates box, enter "resource" and name the file.

    [新しい項目の追加] ダイアログ

  3. キーの値 (ネイティブの文字列) を [名前] 列に入力し、翻訳された文字列を [値] 列に入力します。Enter the key value (native string) in the Name column and the translated string in the Value column.

    Welcome.es.resx ファイル (スペイン語の Welcome リソース ファイル) と、[名前] 列の Hello という単語と、[値] 列の Hola という単語 (スペイン語のこんにちは)

    Visual Studio に Welcome.es.resx ファイルが表示されます。Visual Studio shows the Welcome.es.resx file.

    Welcome スペイン語リソース ファイルを表示しているソリューション エクスプローラー

Visual Studio 2017 Preview バージョン 15.3 を使用している場合、リソース エディターでエラー インジケーターが表示されます。If you are using Visual Studio 2017 Preview version 15.3, you'll get an error indicator in the resource editor. このエラー メッセージを防ぐために、[カスタム ツール] プロパティから ResXFileCodeGenerator 値を削除します。Remove the ResXFileCodeGenerator value from the Custom Tool properties grid to prevent this error message:

Resx エディター

または、このエラーを無視することができます。Alternatively, you can ignore this error. 次のリリースでこの問題を解決する予定です。We hope to fix this in the next release.

リソース ファイルの名前付けResource file naming

リソースの名前は、クラスの完全な型名からアセンブリ名を除いたものになります。Resources are named for the full type name of their class minus the assembly name. たとえば、メイン アセンブリが LocalizationWebsite.Web.dll であるプロジェクト内のクラス LocalizationWebsite.Web.Startup のフランス語のリソースは、Startup.fr.resx という名前になります。For example, a French resource in a project whose main assembly is LocalizationWebsite.Web.dll for the class LocalizationWebsite.Web.Startup would be named Startup.fr.resx. クラス LocalizationWebsite.Web.Controllers.HomeController のリソースは、Controllers.HomeController.fr.resx という名前になります。A resource for the class LocalizationWebsite.Web.Controllers.HomeController would be named Controllers.HomeController.fr.resx. 対象となるクラスの名前空間が、アセンブリ名と同じでない場合は、完全な型名が必要です。If your targeted class's namespace isn't the same as the assembly name you will need the full type name. たとえば、同じプロジェクトで、型 ExtraNamespace.Tools のリソースは、ExtraNamespace.Tools.fr.resx という名前になります。For example, in the sample project a resource for the type ExtraNamespace.Tools would be named ExtraNamespace.Tools.fr.resx.

サンプル プロジェクトで、ConfigureServices メソッドは ResourcesPath を "Resources" に設定するので、ホーム コントローラーのフランス語のりソース ファイルの相対パスは、Resources/Controllers.HomeController.fr.resx です。In the sample project, the ConfigureServices method sets the ResourcesPath to "Resources", so the project relative path for the home controller's French resource file is Resources/Controllers.HomeController.fr.resx. あるいは、フォルダーを使用してリソース ファイルを整理することもできます。Alternatively, you can use folders to organize resource files. Home コント ローラーのパスは、Resources/Controllers/HomeController.fr.resx です。For the home controller, the path would be Resources/Controllers/HomeController.fr.resx. ResourcesPath オプションを使用しない場合、.resx ファイルは、プロジェクトの基本ディレクトリに置かれます。If you don't use the ResourcesPath option, the .resx file would go in the project base directory. HomeController のリソース ファイルは、Controllers.HomeController.fr.resx という名前になります。The resource file for HomeController would be named Controllers.HomeController.fr.resx. ドットまたはパスの名前付け規則の選択は、リソース ファイルを整理する方法によって決まります。The choice of using the dot or path naming convention depends on how you want to organize your resource files.

リソース名Resource name ドットまたはパスの名前付けDot or path naming
Resources/Controllers.HomeController.fr.resxResources/Controllers.HomeController.fr.resx ドットDot
Resources/Controllers/HomeController.fr.resxResources/Controllers/HomeController.fr.resx パスPath

Razor ビューの @inject IViewLocalizer を使用するリソース ファイルは同様のパターンに従います。Resource files using @inject IViewLocalizer in Razor views follow a similar pattern. ビューのリソース ファイルには、ドットの名前付けまたはパスの名前付けを使用して名前を付けることができます。The resource file for a view can be named using either dot naming or path naming. Razor ビューのリソース ファイルは、関連するビュー ファイルのパスを模倣します。Razor view resource files mimic the path of their associated view file. ResourcesPath を "Resources" に設定すると仮定すると、Views/Home/About.cshtml ビューに関連付けられるフランス語のリソース ファイルは、次のいずれかになります。Assuming we set the ResourcesPath to "Resources", the French resource file associated with the Views/Home/About.cshtml view could be either of the following:

  • Resources/Views/Home/About.fr.resxResources/Views/Home/About.fr.resx

  • Resources/Views.Home.About.fr.resxResources/Views.Home.About.fr.resx

ResourcesPath オプションを使用しない場合、ビューの .resx ファイルは、ビューと同じフォルダーに配置されます。If you don't use the ResourcesPath option, the .resx file for a view would be located in the same folder as the view.

カルチャ フォールバック動作Culture fallback behavior

例として、".fr" カルチャ指定子を削除し、カルチャを French に設定した場合、既定のリソース ファイルは read で文字列がローカライズされます。As an example, if you remove the ".fr" culture designator and you have the culture set to French, the default resource file is read and strings are localized. リソース マネージャーは、要求されたカルチャを満たすものがない場合、既定またはフォールバックのリソースを指定します。The Resource manager designates a default or fallback resource for when nothing meets your requested culture. 要求されたカルチャのリソースが見つからないときにキーのみを返す場合は、既定のリソース ファイルを使用することはできません。If you want to just return the key when missing a resource for the requested culture you must not have a default resource file.

Visual Studio でリソース ファイルを生成するGenerate resource files with Visual Studio

Visual Studio で、ファイル名にカルチャを指定せずにリソース ファイルを作成する場合 (たとえば、Welcome.resx)、Visual Studio は各文字列のプロパティを使用して、C# クラスを作成します。If you create a resource file in Visual Studio without a culture in the file name (for example, Welcome.resx), Visual Studio will create a C# class with a property for each string. 通常、ASP.NET Core ではこれを行いません。一般的に既定の .resx リソース ファイル (カルチャ名のない .resx ファイル) は使用しません。That's usually not what you want with ASP.NET Core; you typically don't have a default .resx resource file (A .resx file without the culture name). カルチャ名を含む .resx ファイル (たとえば Welcome.fr.resx) を作成することをお勧めします。We suggest you create the .resx file with a culture name (for example Welcome.fr.resx). カルチャ名を含む .resx ファイルを作成すると、Visual Studio はクラス ファイルを生成しません。When you create a .resx file with a culture name, Visual Studio won't generate the class file. 多くの開発者は既定の言語リソース ファイルを作成しないと予想されます。We anticipate that many developers will not create a default language resource file.

その他のカルチャを追加するAdd Other Cultures

各言語とカルチャの組み合わせ (既定の言語以外) ごとに一意のリソース ファイルが必要です。Each language and culture combination (other than the default language) requires a unique resource file. ISO 言語コードがファイル名の一部となるリソース ファイル (たとえば、en-usfr-caen-gb) を新規作成することで、異なるカルチャとロケールのリソース ファイルを作成することができます。You create resource files for different cultures and locales by creating new resource files in which the ISO language codes are part of the file name (for example, en-us, fr-ca, and en-gb). Welcome.es-MX.resx (スペイン語/メキシコ) のように、ファイル名と .resx ファイル名拡張子の間にこれらの ISO コードが置かれます。These ISO codes are placed between the file name and the .resx file name extension, as in Welcome.es-MX.resx (Spanish/Mexico). カルチャ的にニュートラルな言語を指定するには、国コード (前の例では MX) を削除します。To specify a culturally neutral language, remove the country code (MX in the preceding example). カルチャ的にニュートラルなスペイン語のリソース ファイル名は Welcome.es.resx です。The culturally neutral Spanish resource file name is Welcome.es.resx.

要求ごとに言語/カルチャを選択するための戦略を実装するImplement a strategy to select the language/culture for each request

ローカリゼーションを構成するConfigure localization

ローカリゼーションは、ConfigureServices メソッドで構成されます。Localization is configured in the ConfigureServices method:

services.AddLocalization(options => options.ResourcesPath = "Resources");

services.AddMvc()
    .AddViewLocalization(LanguageViewLocationExpanderFormat.Suffix)
    .AddDataAnnotationsLocalization();
  • AddLocalization ローカリゼーション サービスをサービス コンテナーに追加します。AddLocalization Adds the localization services to the services container. 上記のコードは、リソース パスを "Resources" に設定します。The code above also sets the resources path to "Resources".

  • AddViewLocalization ローカライズされたビュー ファイルのサポートを追加します。AddViewLocalization Adds support for localized view files. このサンプル ビューでは、ローカリゼーションは、ビュー ファイルのサフィックスに基づいています。In this sample view localization is based on the view file suffix. たとえば、Index.fr.cshtml ファイルの "fr" です。For example "fr" in the Index.fr.cshtml file.

  • AddDataAnnotationsLocalization IStringLocalizer 抽象化を介してローカライズされた DataAnnotations 検証メッセージのサポートを追加します。AddDataAnnotationsLocalization Adds support for localized DataAnnotations validation messages through IStringLocalizer abstractions.

ローカリゼーション ミドルウェアLocalization middleware

要求時に現在のカルチャが、ローカリゼーション ミドルウェアで設定されます。The current culture on a request is set in the localization Middleware. ローカリゼーション ミドルウェアは、Configure メソッドで有効になります。The localization middleware is enabled in the Configure method. 要求のカルチャをチェックする可能性があるすべてのミドルウェア (たとえば app.UseMvcWithDefaultRoute()) の前に、ローカリゼーション ミドルウェアを構成する必要があります。The localization middleware must be configured before any middleware which might check the request culture (for example, app.UseMvcWithDefaultRoute()).

var supportedCultures = new[]
{
    new CultureInfo(enUSCulture),
    new CultureInfo("en-AU"),
    new CultureInfo("en-GB"),
    new CultureInfo("en"),
    new CultureInfo("es-ES"),
    new CultureInfo("es-MX"),
    new CultureInfo("es"),
    new CultureInfo("fr-FR"),
    new CultureInfo("fr"),
};

app.UseRequestLocalization(new RequestLocalizationOptions
{
    DefaultRequestCulture = new RequestCulture(enUSCulture),
    // Formatting numbers, dates, etc.
    SupportedCultures = supportedCultures,
    // UI strings that we have localized.
    SupportedUICultures = supportedCultures
});

app.UseStaticFiles();
// To configure external authentication, 
// see: http://go.microsoft.com/fwlink/?LinkID=532715
app.UseAuthentication();
app.UseMvcWithDefaultRoute();

UseRequestLocalizationRequestLocalizationOptions オブジェクトを初期化します。UseRequestLocalization initializes a RequestLocalizationOptions object. すべての要求で、RequestLocalizationOptionsRequestCultureProvider のリストが列挙され、要求のカルチャを正常に決定できる最初のプロバイダーが使用されます。On every request the list of RequestCultureProvider in the RequestLocalizationOptions is enumerated and the first provider that can successfully determine the request culture is used. 既定のプロバイダーは RequestLocalizationOptions クラスから派生します。The default providers come from the RequestLocalizationOptions class:

  1. QueryStringRequestCultureProvider
  2. CookieRequestCultureProvider
  3. AcceptLanguageHeaderRequestCultureProvider

既定のリストは、最も具体的なものから最も具体的でないものの順番になります。The default list goes from most specific to least specific. 記事の後半では、この順序を変更する方法、さらにカスタム カルチャ プロバイダーを追加する方法も説明します。Later in the article we'll see how you can change the order and even add a custom culture provider. 要求のカルチャを判断できるプロバイダーがない場合、DefaultRequestCulture が使用されます。If none of the providers can determine the request culture, the DefaultRequestCulture is used.

QueryStringRequestCultureProviderQueryStringRequestCultureProvider

いくつかのアプリでは、クエリ文字列を使用して、カルチャおよび UI カルチャを設定します。Some apps will use a query string to set the culture and UI culture. Cookie または Accept-language ヘッダーのアプローチを使用するアプリの場合、URL にクエリ文字列を追加すると、デバッグおよびコードのテストに役立ちます。For apps that use the cookie or Accept-Language header approach, adding a query string to the URL is useful for debugging and testing code. 既定では、QueryStringRequestCultureProvider が、RequestCultureProvider リストの最初のローカリゼーション プロバイダーとして登録されます。By default, the QueryStringRequestCultureProvider is registered as the first localization provider in the RequestCultureProvider list. クエリ文字列パラメーター cultureui-culture を渡します。You pass the query string parameters culture and ui-culture. 次の例では、特定のカルチャ (言語および地域) をスペイン語/メキシコに設定します。The following example sets the specific culture (language and region) to Spanish/Mexico:

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

2 つのいずれかのみ (culture または ui-culture) を渡した場合、クエリ文字列プロバイダーは、渡した 1 つのパラメーターを使用して両方の値を設定します。If you only pass in one of the two (culture or ui-culture), the query string provider will set both values using the one you passed in. たとえば、カルチャだけを設定すると、CultureUICulture の両方が設定されます。For example, setting just the culture will set both the Culture and the UICulture:

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

CookieRequestCultureProviderCookieRequestCultureProvider

多くの場合、実稼働アプリケーションは、ASP.NET Core カルチャ Cookie を使用してカルチャを設定するためのメカニズムを提供します。Production apps will often provide a mechanism to set the culture with the ASP.NET Core culture cookie. Cookie を作成するには、MakeCookieValue メソッドを使用します。Use the MakeCookieValue method to create a cookie.

CookieRequestCultureProvider DefaultCookieName は、ユーザーの優先するカルチャ情報を追跡するために使用される既定の Cookie 名を返します。The CookieRequestCultureProvider DefaultCookieName returns the default cookie name used to track the user's preferred culture information. 既定の Cookie 名は .AspNetCore.Culture です。The default cookie name is .AspNetCore.Culture.

Cookie の形式は c=%LANGCODE%|uic=%LANGCODE% です。ここで、cCulture であり、uicUICulture です。たとえば、次のようになります。The cookie format is c=%LANGCODE%|uic=%LANGCODE%, where c is Culture and uic is UICulture, for example:

c=en-UK|uic=en-US

カルチャ情報と UI カルチャの 1 つのみを指定した場合、指定したカルチャが、カルチャ情報と UI カルチャの両方に使用されます。If you only specify one of culture info and UI culture, the specified culture will be used for both culture info and UI culture.

Accept-Language HTTP ヘッダーThe Accept-Language HTTP header

Accept-language ヘッダーは、ほとんどのブラウザーで設定可能であり、当初はユーザーの言語を指定するためのものでした。The Accept-Language header is settable in most browsers and was originally intended to specify the user's language. この設定は、ブラウザーが何を送信するように設定されているか、基になるオペレーティング システムから何を継承するかを示します。This setting indicates what the browser has been set to send or has inherited from the underlying operating system. ブラウザーの要求からの Accept Language HTTP ヘッダーは、ユーザーの優先言語を検出するための確実な方法ではありません (「Setting language preferences in a browser」(ブラウザーの優先言語を設定する) を参照してください)。The Accept-Language HTTP header from a browser request isn't an infallible way to detect the user's preferred language (see Setting language preferences in a browser). 実稼働アプリには、ユーザーがカルチャの選択をカスタマイズする方法を含める必要があります。A production app should include a way for a user to customize their choice of culture.

IE で Accept-Language HTTP ヘッダーを設定するSet the Accept-Language HTTP header in IE

  1. 歯車アイコンから、[インターネット オプション] をタップします。From the gear icon, tap Internet Options.

  2. [言語] をタップします。Tap Languages.

    インターネット オプション

  3. [言語の優先順位の設定] をタップします。Tap Set Language Preferences.

  4. [言語の追加] をタップします。Tap Add a language.

  5. 言語を追加します。Add the language.

  6. 言語をタップして、[上へ移動] をタップします。Tap the language, then tap Move Up.

カスタム プロバイダーを使用するUse a custom provider

お客様がデータベースに言語とカルチャを格納できるようにしたいとします。Suppose you want to let your customers store their language and culture in your databases. ユーザーのためにこれらの値を検索するプロバイダーを記述することもできます。You could write a provider to look up these values for the user. 次のコードは、カスタム プロバイダーを追加する方法を示しています。The following code shows how to add a custom provider:

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.RequestCultureProviders.Insert(0, new CustomRequestCultureProvider(async context =>
    {
        // My custom request culture logic
        return new ProviderCultureResult("en");
    }));
});

ローカリゼーション プロバイダーを追加または削除するには、RequestLocalizationOptions を使用します。Use RequestLocalizationOptions to add or remove localization providers.

プログラムでカルチャを設定するSet the culture programmatically

この GitHub のサンプル Localization.StarterWeb プロジェクトには、Culture を設定するための UI が含まれています。This sample Localization.StarterWeb project on GitHub contains UI to set the Culture. Views/Shared/_SelectLanguagePartial.cshtml ファイルを使用して、サポートされているカルチャの一覧からカルチャを選択することができます。The Views/Shared/_SelectLanguagePartial.cshtml file allows you to select the culture from the list of supported cultures:

@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 セクションに追加されるので、すべてのビューで使用できます。The Views/Shared/_SelectLanguagePartial.cshtml file is added to the footer section of the layout file so it will be available to all views:

<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.StarterWeb</p>
            </div>
            <div class="col-md-6 text-right">
                @await Html.PartialAsync("_SelectLanguagePartial")
            </div>
        </div>
    </footer>
</div>

SetLanguage メソッドはカルチャ Cookie を設定します。The SetLanguage method sets the culture 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 をこのプロジェクトのサンプル コードに接続することはできません。You can't plug in the _SelectLanguagePartial.cshtml to sample code for this project. GitHubLocalization.StarterWeb プロジェクトには、依存関係の挿入コンテナーを介して Razor 部分に RequestLocalizationOptions を挿入するコードがあります。The Localization.StarterWeb project on GitHub has code to flow the RequestLocalizationOptions to a Razor partial through the Dependency Injection container.

グローバリゼーションとローカリゼーションの用語Globalization and localization terms

アプリをローカライズするプロセスでは、最新のソフトウェア開発でよく使用される関連する文字セットの基本的な理解と、それらに関連した問題の理解も必要です。The process of localizing your app also requires a basic understanding of relevant character sets commonly used in modern software development and an understanding of the issues associated with them. すべてのコンピューターは、テキストを数値 (コード) として格納しますが、さまざまなシステムが異なる数値を使用して同じテキストを格納します。Although all computers store text as numbers (codes), different systems store the same text using different numbers. ローカリゼーション プロセスとは、特定のカルチャ/ロケール用にアプリのユーザー インターフェイス (UI) を変換することを指します。The localization process refers to translating the app user interface (UI) for a specific culture/locale.

ローカライズ化は、グローバル化されたアプリのローカリゼーションの準備ができていることを確認するための中間プロセスです。Localizability is an intermediate process for verifying that a globalized app is ready for localization.

カルチャ名の RFC 4646 形式は <languagecode2>-<country/regioncode2> です。ここで、<languagecode2> は言語コードであり、<country/regioncode2> はサブカルチャ コードです。The RFC 4646 format for the culture name is <languagecode2>-<country/regioncode2>, where <languagecode2> is the language code and <country/regioncode2> is the subculture code. たとえば、スペイン語 (チリ) は es-CL、英語 (米国) は en-US、英語 (オーストラリア) は en-AU です。For example, es-CL for Spanish (Chile), en-US for English (United States), and en-AU for English (Australia). RFC 4646 は、言語に関連付けられた ISO 639 の 2 文字の小文字カルチャ コードと、国または地域に関連付けられた ISO 3166 の 2 文字の大文字サブカルチャ コードの組み合わせです。RFC 4646 is a combination of an ISO 639 two-letter lowercase culture code associated with a language and an ISO 3166 two-letter uppercase subculture code associated with a country or region. Language Culture Name」(言語カルチャ名) を参照してください。See Language Culture Name.

多くの場合、国際化は "I18N" に省略されます。Internationalization is often abbreviated to "I18N". 省略形は、最初と最後の文字およびそれらの間の文字の数になります。したがって、18 は、最初の "I" と最後の "N" の間の文字の数を表します。The abbreviation takes the first and last letters and the number of letters between them, so 18 stands for the number of letters between the first "I" and the last "N". 同じことが、グローバリゼーション (G11N) とローカリゼーション (L10N) にも当てはまります。The same applies to Globalization (G11N), and Localization (L10N).

用語:Terms:

  • グローバリゼーション (G11N): アプリが別の言語と地域をサポートするようにするプロセス。Globalization (G11N): The process of making an app support different languages and regions.
  • ローカリゼーション (L10N): 特定の言語と地域向けにアプリをカスタマイズするプロセス。Localization (L10N): The process of customizing an app for a given language and region.
  • 国際化 (I18N): グローバリゼーションとローカリゼーションの両方を示します。Internationalization (I18N): Describes both globalization and localization.
  • カルチャ: 言語および必要に応じて地域です。Culture: It's a language and, optionally, a region.
  • ニュートラル カルチャ: 指定した言語のみを含み、地域は含まないカルチャ Neutral culture: A culture that has a specified language, but not a region. (例: "en"、"es")。(for example "en", "es")
  • 特定のカルチャ: 指定した言語と地域を含むカルチャ Specific culture: A culture that has a specified language and region. (例: "en-US"、"en-GB"、"es-CL")。(for example "en-US", "en-GB", "es-CL")
  • 親カルチャ: 特定のカルチャを含むニュートラル カルチャ Parent culture: The neutral culture that contains a specific culture. (たとえば、"en" は "en-US" および "en-GB" の親カルチャです)。(for example, "en" is the parent culture of "en-US" and "en-GB")
  • ロケール: ロケールはカルチャと同じです。Locale: A locale is the same as a culture.

その他の技術情報Additional resources