グローバリゼーションとローカリゼーション ASP.NET CoreGlobalization and localization in ASP.NET Core

によってRick AndersonDamien BowdenBart CalixtoNadeem Afana、およびHisham 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. 次のコードでは、ローカライズ文字列「タイトルは」をラップする方法を示します。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. 「タイトルは」のローカライズされた値が見つからないかどうかは、インデクサーのキーが返されます、つまり、文字列「タイトルは」です。If the localized value of "About Title" is not 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.

使用して、 IHtmlLocalizer<T> HTML を格納しているリソースの実装です。Use the IHtmlLocalizer<T> implementation for resources that contain HTML. IHtmlLocalizerHTML エンコードされたリソース文字列で書式設定される引数が、HTML ではありませんは、リソース文字列そのものをエンコードします。IHtmlLocalizer HTML encodes arguments that are formatted in the resource string, but does not 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 is no option to use a global shared resource file. ViewLocalizer実装を使用してローカライザー IHtmlLocalizerRazor しない HTML のため、ローカライズされた文字列をエンコードします。ViewLocalizer implements the localizer using IHtmlLocalizer, so Razor doesn't HTML encode the localized string. リソース文字列をパラメーター化できるとIViewLocalizerHTML エンコードされますが、パラメーター、リソース文字列ではありません。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 e-mail 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 では、2 つのカルチャ値を指定できます。SupportedCulturesSupportedUICulturesです。ASP.NET Core allows you to specify two culture values, SupportedCultures and SupportedUICultures. CultureInfoオブジェクトに対するSupportedCultures日付、時刻、数、および通貨の書式設定など、カルチャに依存する関数の結果を決定します。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 is determined by CurrentUICulture. .NET のすべてのスレッドがCurrentCultureCurrentUICultureオブジェクト。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()場合は、「木曜日、2016 年 2 月 18日」が表示されます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".

リソース ファイルの操作Working with 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. 検索には、テンプレートがインストールされているボックスで、「リソース」を入力し、ファイルの名前します。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.

    Hello の 名前 列と 値 列内の単語 Hola (スペイン語でのこんにちは) Welcome.es.resx ファイル (へようこそ のリソース ファイルのスペイン語)

    Visual Studio の表示、 Welcome.es.resxファイル。Visual Studio shows the Welcome.es.resx file.

    ソリューション エクスプ ローラーのようこそスペイン語 (es) のリソース ファイルを表示

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 is not 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 「リソース」をそのため、home コント ローラーのフランス語りソース ファイルのプロジェクトの相対パスは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

リソース ファイルを使用して@inject IViewLocalizerRazor ビューで、同様のパターンに従います。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に「リソース」、フランス語のリソース ファイルに関連付けられて、 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.

".Fr"カルチャの指定子を削除し、カルチャをフランス語 (cookie または他の機構) 経由での設定を使用している場合は、既定のリソース ファイルは読み取りし、文字列はローカライズします。If you remove the ".fr" culture designator AND you have the culture set to French (via cookie or other mechanism), the default resource file is read and strings are localized. リソース マネージャーは、何も行われませんが、カルチャの指定子なし *.resx ファイルを処理している、要求されたカルチャを満たす場合、既定値またはフォールバック リソースを指定します。The Resource manager designates a default or fallback resource, when nothing meets your requested culture you're served the *.resx file without a culture designator. 要求されたカルチャのリソースが見つかりません必要があります、既定のリソース ファイルは持っていない場合にだけ、キーを返す場合は。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 でのリソース ファイルを生成します。Generating 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リソース ファイル (A .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 will not generate the class file. 多くの開発者にいない既定の言語リソース ファイルを作成します。We anticipate that many developers will not create a default language resource file.

その他のカルチャを追加します。Adding Other Cultures

(既定の言語) 以外の言語とカルチャの組み合わせごとに一意のリソース ファイルが必要です。Each language and culture combination (other than the default language) requires a unique resource file. ISO 言語コードがファイル名の一部となるリソース ファイルの新規作成して異なるカルチャとロケールのリソース ファイルを作成する (たとえば、 en-usfr ca、およびen 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). これらの ISO コードを配置しているファイル名の間、 .resxファイル名拡張子としてWelcome.es MX.resx (スペイン語/メキシコ)。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

ローカリゼーションの構成Configuring 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. 上記のコードは、「リソース」のリソース パスを設定します。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. たとえば"fr"で、 Index.fr.cshtmlファイル。For example "fr" in the Index.fr.cshtml file.

  • AddDataAnnotationsLocalizationローカライズのサポートが追加されてDataAnnotationsを介してメッセージを検証IStringLocalizer抽象化します。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メソッドのProgram.csファイル。The localization middleware is enabled in the Configure method of Program.cs file. 要求のカルチャをチェックするすべてのミドルウェアの前に、ローカリゼーション ミドルウェアを構成する必要があります、注意してください (たとえば、 app.UseMvcWithDefaultRoute())。Note, 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();

UseRequestLocalization初期化、RequestLocalizationOptionsオブジェクト。UseRequestLocalization initializes a RequestLocalizationOptions object. すべての要求リストのRequestCultureProviderで、RequestLocalizationOptionsが列挙され、要求のカルチャが正常に決定できる最初のプロバイダーが使用されます。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. をクッキーまたは 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. 使用して、 MakeCookieValue cookie を作成します。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%ここで、cCultureuicUICulture例。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 カルチャのいずれかの場合、指定されたカルチャはカルチャ情報と 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.

ブラウザーの言語の 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 ヘッダーは、ユーザーの優先言語を検出するない方法ではありません (を参照してくださいブラウザーの言語設定を設定する)。The Accept-Language HTTP header from a browser request is not 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 ヘッダーの設定Setting 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.

カスタム プロバイダーを使用します。Using 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.

プログラムによる、カルチャの設定Setting the culture programmatically

このサンプルLocalization.StarterWebプロジェクトでは、 GitHubを設定するための UI が含まれています、Cultureです。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. Localization.StarterWebプロジェクトでは、 GitHubフローするコードが含ま、RequestLocalizationOptionsを通じて部分 Razor を依存性の注入コンテナーです。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カルチャ名の書式を設定"-< country/regioncode2 >"ここで、言語コードは、< country/regioncode2 > となりです。The RFC 4646 format for the culture name is "-<country/regioncode2>", where 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 文字の小文字のカルチャ コードと国または地域に関連付けられている 2 文字の大文字となり、ISO 3166 の組み合わせです。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. 参照してください言語カルチャ名です。See Language Culture Name.

国際化は、"I18N"に多くの場合、省略されています。Internationalization is often abbreviated to "I18N". 省略形は、最初と最後の文字を受け取り、それらの間でため 18 文字の数は、最後の"N"、"I"、最初の文字の数を意味します。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 is 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