ASP.NET Core アプリで言語とカルチャ用にローカライズされたリソースを提供する

作成者: Rick Anderson、Damien Bowden、Bart Calixto、Nadeem Afana、Hisham Bin Ateya

アプリをローカライズするためのタスクの 1 つは、リソース ファイルでローカライズされた文字列を提供することです。 この記事では、リソース ファイルの使用について説明します。

SupportedCultures および SupportedUICultures

ASP.NET Core には、SupportedCultures と SupportedUICultures という 2 つのカルチャ値のコレクションがあります。 日付、数値、および通貨の書式設定など、カルチャに依存する関数の結果は、SupportedCultures の CultureInfo オブジェクトによって決まります。 テキストの並べ替え順序、大文字と小文字の表記規則、文字列比較も SupportedCultures によって決まります。 サーバーがカルチャを取得する方法の詳細については、「StringComparer.CurrentCulture」を参照してください。 .resx ファイルからのどの翻訳文字列が ResourceManager によって検索されるのかが SupportedUICultures で決まります。 ResourceManager は、CurrentUICulture によって決定されるカルチャ固有の文字列を単に検索します。 .NET のすべてのスレッドに CurrentCulture オブジェクトと CurrentUICultureオブジェクトがあります。 ASP.NET Core は、カルチャに依存する関数を表示するときに、これらの値を検査します。 たとえば、現在のスレッドのカルチャが "en-US" (英語、米国) に設定されている場合は、DateTime.Now.ToLongDateString() は、"Thursday, February 18, 2016" を表示しますが、CurrentCulture が "es-ES" (スペイン語、スペイン) に設定されている場合、出力は "jueves, 18 de febrero de 2016" になります。

リソース ファイル

注:ResX ビューアーとエディターには、Visual Studio Code を使用してリソース ファイルを操作するための代替メカニズムが用意されています。

リソース ファイルは、ローカライズ可能な文字列をコードから分離するために役立つメカニズムです。 既定以外の言語の翻訳された文字列は、 .resx リソース ファイルで分離されています。 たとえば、翻訳された文字列を含む Welcome.es.resx という名前のスペイン語のリソース ファイルを作成したい場合があります。 "es" は、スペイン語の言語コードです。 Visual Studio でこのリソース ファイルを作成するには、次の手順を実行します。

1. ソリューション エクスプローラーで、リソース ファイルを含めるフォルダーを右クリックし、[追加]>[新しい項目] の順に選択します。

   

2. インストールされているテンプレートの検索ボックスに、「resource」と入力し、ファイルに名前を付けます。

   

3. キーの値 (ネイティブの文字列) を [名前] 列に入力し、翻訳された文字列を [値] 列に入力します。

   

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

   

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

リソースの名前は、クラスの完全な型名からアセンブリ名を除いたものになります。 たとえば、メイン アセンブリが LocalizationWebsite.Web.dll であるプロジェクト内のクラス LocalizationWebsite.Web.Startup のフランス語のリソースは、Startup.fr.resx という名前になります。 クラス LocalizationWebsite.Web.Controllers.HomeController のリソースは、Controllers.HomeController.fr.resx という名前になります。 対象となるクラスの名前空間が、アセンブリ名と同じでない場合は、完全な型名が必要です。 たとえば、同じプロジェクトで、型 ExtraNamespace.Tools のリソースは、ExtraNamespace.Tools.fr.resx という名前になります。

サンプル プロジェクトで、ConfigureServices メソッドにより ResourcesPath が "Resources" に設定されるので、ホーム コントローラーのフランス語のリソース ファイルの相対パスは、Resources/Controllers.HomeController.fr.resx です。 あるいは、フォルダーを使用してリソース ファイルを整理することもできます。 ホーム コントローラーのパスは、Resources/Controllers/HomeController.fr.resx です。 ResourcesPath オプションを使用しない場合、 .resx ファイルは、プロジェクトの基本ディレクトリに置かれます。 HomeController のリソース ファイルは、Controllers.HomeController.fr.resx という名前になります。 ドットまたはパスの名前付け規則の選択は、リソース ファイルを整理する方法によって決まります。

リソース名	ドットまたはパスの名前付け
Resources/Controllers.HomeController.fr.resx	ドット
Resources/Controllers/HomeController.fr.resx	パス

Razor ビューの @inject IViewLocalizer を使用するリソース ファイルは同様のパターンに従います。 ビューのリソース ファイルには、ドットの名前付けまたはパスの名前付けを使用して名前を付けることができます。 Razor ビューのリソース ファイルは、関連するビュー ファイルのパスを模倣します。 ResourcesPath を "Resources" に設定すると仮定すると、Views/Home/About.cshtml ビューに関連付けられるフランス語のリソース ファイルは、次のいずれかになります。

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

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

ResourcesPath オプションを使用しない場合、ビューの .resx ファイルは、ビューと同じフォルダーに配置されます。

RootNamespaceAttribute

アセンブリのルート名前空間がアセンブリ名と異なると、RootNamespaceAttribute 属性によってアセンブリのルート名前空間が提供されます。

警告

これは、プロジェクト名が有効な .NET 識別子でない場合に発生する可能性があります。 たとえば、my-project-name.csproj ではルート名前空間 my_project_name が使用されるので、アセンブリ名 my-project-name はこのエラーにつながります。

アセンブリのルート名前空間がアセンブリ名と異なる場合:

• 既定では、ローカライズが機能しません。
• アセンブリ内でのリソースの検索方法が原因で、ローカライズが失敗します。 RootNamespace はビルド時の値で、実行中のプロセスでは使用できません。

RootNamespace が AssemblyName と異なる場合、AssemblyInfo.cs (パラメーターの値は実際の値に置き換えられます) に次を含めてください。

using System.Reflection;
using Microsoft.Extensions.Localization;

[assembly: ResourceLocation("Resource Folder Name")]
[assembly: RootNamespace("App Root Namespace")]

上記のコードにより、resx ファイルが正常に解決できるようになります。

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

リソースを探すとき、ローカリゼーションは、"カルチャ フォールバック" を行います。 要求されたカルチャが存在しない場合、そのカルチャの親カルチャに戻ります。 なお、CultureInfo.Parent プロパティは親カルチャを示します。 つまり、通常は (必ずではありませんが) 言語とカルチャのコードから国の識別子が削除されます。 たとえば、メキシコで使われているスペイン語は、"es-MX" です。 これには、どの国にも固有でないスペイン語の "es" が親として付いています。

カルチャ "fr-CA" が使用された、"ようこそ" リソースの要求をサイトで受信するとします。 ローカリゼーション システムでは、次の順番でリソースを検索し、最初の一致を選択します。

• Welcome.fr-CA.resx
• Welcome.fr.resx
• Welcome.resx (NeutralResourcesLanguage が "fr-CA" の場合)

例として、".fr" カルチャ指定子を削除し、カルチャを French に設定した場合、既定のリソース ファイルは read で文字列がローカライズされます。 リソース マネージャーは、要求されたカルチャを満たすものがない場合、既定またはフォールバックのリソースを指定します。 要求されたカルチャのリソースが見つからないときにキーのみを返す場合は、既定のリソース ファイルを使用することはできません。

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

Visual Studio で、ファイル名にカルチャを指定せずにリソース ファイルを作成する場合 (たとえば、Welcome.resx)、Visual Studio は各文字列のプロパティを使用して、C# クラスを作成します。 通常、ASP.NET Core ではこれを行いません。 一般的に既定の .resx リソース ファイル (カルチャ名のない .resx ファイル) は使用しません。 カルチャ名を含む .resx ファイル (たとえば Welcome.fr.resx) を作成することをお勧めします。 カルチャ名を含む .resx ファイルを作成すると、Visual Studio はクラス ファイルを生成しません。

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

各言語とカルチャの組み合わせ (既定の言語以外) ごとに一意のリソース ファイルが必要です。 言語コードがファイル名の一部となる新しいリソース ファイル (たとえば、en-us、fr-ca、en-gb) を作成することで、異なるカルチャとロケールのリソース ファイルを作成することができます。 これらのコードは、Welcome.es-MX.resx (スペイン語/メキシコ) のように、ファイル名と .resx ファイル拡張子の間に置かれます。

次のステップ

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

• アプリのコンテンツをローカライズ可能にする。
• 要求ごとに言語/カルチャを選択するための戦略を実装する

その他のリソース

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