ローカライズされた NuGet パッケージを作成するCreating localized NuGet packages

ライブラリのローカライズされたバージョンを作成する方法は 2 つあります。There are two ways to create localized versions of a library:

  1. 1 つのパッケージにローカライズされたすべてのリソース アセンブリを含めます。Include all localized resources assemblies in a single package.
  2. 厳密な一連の規則に従って、個別のローカライズされたサテライト パッケージを作成します。Create separate localized satellite packages by following a strict set of conventions.

どちらの方法にも、次のセクションで説明するようなメリットとデメリットがあります。Both methods have their advantages and disadvantages, as described in the following sections.

1 つのパッケージにローカライズされたすべてのリソース アセンブリを含めるLocalized resource assemblies in a single package

ローカライズされたリソース アセンブリを 1 つのパッケージに含めるのが、通常、最も簡単なアプローチです。Including localized resource assemblies in a single package is typically the simplest approach. これを行うには、パッケージの既定 (en-us と見なされます) 以外のサポートされる言語の lib 内にフォルダーを作成します。To do this, create folders within lib for supported language other than the package default (assumed to be en-us). これらのフォルダーには、リソース アセンブリおよびローカライズされた IntelliSense XML ファイルを配置できます。In these folders you can place resource assemblies and localized IntelliSense XML files.

たとえば、次のフォルダー構造は、ドイツ語 (de)、イタリア語 (it)、日本語 (ja)、ロシア語 (ru)、簡体字中国語 (zh-Hans)、および繁体字中国語 (zh-Hant) をサポートします。For example, the following folder structure supports, German (de), Italian (it), Japanese (ja), Russian (ru), Chinese (Simplified) (zh-Hans), and Chinese (Traditional) (zh-Hant):

lib
└───net40
    │   Contoso.Utilities.dll
    │   Contoso.Utilities.xml
    │
    ├───de
    │       Contoso.Utilities.resources.dll
    │       Contoso.Utilities.xml
    │
    ├───it
    │       Contoso.Utilities.resources.dll
    │       Contoso.Utilities.xml
    │
    ├───ja
    │       Contoso.Utilities.resources.dll
    │       Contoso.Utilities.xml
    │
    ├───ru
    │       Contoso.Utilities.resources.dll
    │       Contoso.Utilities.xml
    │
    ├───zh-Hans
    │       Contoso.Utilities.resources.dll
    │       Contoso.Utilities.xml
    │
    └───zh-Hant
            Contoso.Utilities.resources.dll
            Contoso.Utilities.xml

すべての言語は net40 ターゲット フレームワーク フォルダーの下に一覧表示されます。You can see that the languages are all listed underneath the net40 target framework folder. 複数のフレームワークをサポートする場合、lib の下に各バリアントのフォルダーがあります。If you're supporting multiple frameworks, then you have a folder under lib for each variant.

これらのフォルダーを配置して、.nuspec 内ですべてのファイルを参照します。With these folders in place, you then reference all the files in your .nuspec:

<?xml version="1.0"?>
<package>
    <metadata>...
    </metadata>
    <files>
    <file src="lib\**" target="lib" />
    </files>
</package>

この手法を使用しする 1 つのサンプル パッケージは Microsoft.Data.OData 5.4.0 です。One example package that uses this approach is Microsoft.Data.OData 5.4.0.

メリットとデメリット (ローカライズされたリソース アセンブリ)Advantages and disadvantages (localized resource assemblies)

1 つのパッケージにすべての言語をビルドすることには、次のようないくつかのデメリットがあります。Bundling all languages in a single package has a few disadvantages:

  1. 共有メタデータ: NuGet パッケージは、1 つの .nuspec ファイルのみを含めることができるので、1 つの言語のメタデータだけを提供できます。Shared metadata: Because a NuGet package can only contain a single .nuspec file, you can provide metadata for only a single language. つまり、NuGet は、ローカライズされたメタデータのサポートを提供しません。That is, NuGet does not present support localized metadata.
  2. パッケージのサイズ: サポートする言語の数によっては、ライブラリがかなり大きくなる可能性があり、パッケージのインストールと復元の速度が低下します。Package size: Depending on the number of languages you support, the library can become considerably large, which slows installing and restoring the package.
  3. 同時リリース: 1 つのパッケージ内にローカライズされたファイルをバンドルするには、そのパッケージ内ですべての資産を同時にリリースする必要があり、個別に各ローカライズをリリースすることはできません。Simultaneous releases: Bundling localized files into a single package requires that you release all assets in that package simultaneously, rather than being able to release each localization separately. さらに、1 つのローカライズに何らかの更新があった場合には、パッケージ全体の新しいバージョンが必要です。Furthermore, any update to any one localization requires a new version of the entire package.

ただし、いくつかのメリットもあります。However, it also has a few benefits:

  1. シンプル: パッケージのコンシューマーは、1 つのインストールでサポートされているすべての言語を取得し、各言語を個別にインストールする必要がありません。Simplicity: Consumers of the package get all supported languages in a single install, rather than having to install each language separately. 1 つのパッケージは、nuget.org で見つけやすくもなります。A single package is also easier to find on nuget.org.
  2. 組み合わせたバージョン: すべてのリソース アセンブリが、プライマリ アセンブリと同じパッケージ内にあるので、それらのすべてが同じバージョン番号を共有し、誤って切り離されるリスクがなくなります。Coupled versions: Because all of the resource assemblies are in the same package as the primary assembly, they all share the same version number and don't run a risk of getting erroneously decoupled.

ローカライズされたサテライト パッケージLocalized satellite packages

.NET Framework でのサテライト アセンブリのサポート方法と同様に、この方法では、ローカライズされたリソースと IntelliSense XML ファイルをサテライト パッケージに分割します。Similar to how .NET Framework supports satellite assemblies, this method separates localized resources and IntelliSense XML files into satellite packages.

これを行うには、プライマリ パッケージで、名前付け規則 {identifier}.{version}.nupkg を使用し、既定の言語 (en-US など) などのアセンブリを含めます。Do to this, your primary package uses the naming convention {identifier}.{version}.nupkg and contains the assembly for the default language (such as en-US). たとえば、ContosoUtilities.1.0.0.nupkg には、次の構造が含まれます。For example, ContosoUtilities.1.0.0.nupkg would contain the following structure:

lib
└───net40
        ContosoUtilities.dll
        ContosoUtilities.xml

サテライト アセンブリは、ContosoUtilities.de.1.0.0.nupkg などのように名前付け規則 {identifier}.{language}.{version}.nupkgを使用します。A satellite assembly then uses the naming convention {identifier}.{language}.{version}.nupkg, such as ContosoUtilities.de.1.0.0.nupkg. 識別子は、プライマリ パッケージと完全に一致している必要がありますThe identifier must exactly match that of the primary package.

これは、個別のパッケージに独自の .nuspec ファイルがあり、それがローカライズされたメタデータを含んでいるためです。Because this is a separate package, it has its own .nuspec file that contains localized metadata. .nuspec の言語は、ファイル名で使用されるものと一致している必要がありますBe mindful that the language in the .nuspec must match the one used in the filename.

サテライト アセンブリは、[] バージョン表記を使用して (「Package versioning」(パッケージのバージョン管理) を参照してください)、プライマリ パッケージの正確なバージョンを宣言する必要もありますThe satellite assembly must also declare an exact version of the primary package as a dependency, using the [] version notation (see Package versioning). たとえば、ContosoUtilities.de.1.0.0.nupkg は、[1.0.0] 表記を使用して ContosoUtilities.1.0.0.nupkg で依存関係を宣言する必要があります。For example, ContosoUtilities.de.1.0.0.nupkg must declare a dependency on ContosoUtilities.1.0.0.nupkg using the [1.0.0] notation. サテライト パッケージでは、当然ながら、プライマリ パッケージと別のバージョン番号を付けることができます。The satellite package can, of course, have a different version number than the primary package.

サテライト パッケージの構造で、パッケージ ファイル名の {language} と一致するサブフォルダーにリソース アセンブリと XML IntelliSense ファイルを含める必要があります。The satellite package's structure must then include the resource assembly and XML IntelliSense file in a subfolder that matches {language} in the package filename:

lib
└───net40
    └───de
            ContosoUtilities.resources.dll
            ContosoUtilities.xml

: ja-JP などの特定のサブカルチャが必要な場合を除いて、ja のような高レベルの言語識別子を常に使用してください。Note: unless specific subcultures such as ja-JP are necessary, always use the higher level language identifier, like ja.

サテライト アセンブリで、NuGet は、ファイル名の {language} と一致するフォルダー内のファイルのみを認識します。In a satellite assembly, NuGet will recognize only those files in the folder that matches the {language} in the filename. 他の属性はすべて無視されます。All others are ignored.

これらのすべての規則が満たされたら、NuGet は、サテライト パッケージとしてパッケージを認識し、プライマリ パッケージの lib フォルダーにローカライズされたファイルをインストールします。それらがもともとバンドルされている場合と同様です。When all of these conventions are met, NuGet will recognize the package as a satellite package and install the localized files into the primary package's lib folder, as if they had been originally bundled. サテライト パッケージをアンインストールすると、その同じフォルダーからそのファイルが削除されます。Uninstalling the satellite package will remove its files from that same folder.

サポートされている言語ごとに同じ方法で、追加のサテライト アセンブリを作成します。You would create additional satellite assemblies in the same way for each supported language. 例については、ASP.NET MVC のパッケージのセットを確認してください。For an example, examine the set of ASP.NET MVC packages:

必要な規則の概要Summary of required conventions

  • プライマリ パッケージの名前を指定する必要があります。{identifier}.{version}.nupkgPrimary package must be named {identifier}.{version}.nupkg
  • サテライト パッケージの名前を指定する必要があります。{identifier}.{language}.{version}.nupkgA satellite package must be named {identifier}.{language}.{version}.nupkg
  • サテライト パッケージの .nuspec でファイル名に一致する言語を指定する必要があります。A satellite package's .nuspec must specify its language to match the filename.
  • サテライト パッケージは、.nuspec ファイルで [] 表記を使用して、プライマリの正確なバージョンで依存関係を宣言する必要があります。A satellite package must declare a dependency on an exact version of the primary using the [] notation in its .nuspec file. 範囲はサポートされていません。Ranges are not supported.
  • サテライト パッケージは、ファイルの {language} と正確に一致する lib\[{framework}\]{language} フォルダー内にファイルを配置する必要があります。A satellite package must place files in the lib\[{framework}\]{language} folder that exactly matches {language} in the filename.

メリットとデメリット (サテライトのパッケージ)Advantages and disadvantages (satellite packages)

サテライトのパッケージを使用すると、いくつかのメリットがあります。Using satellite packages has a few benefits:

  1. パッケージのサイズ: プライマリ パッケージの全体的な大きさが最小限に抑えられ、コンシューマーには、使用する各言語のコストのみが発生します。Package size: The overall footprint of the primary package is minimized, and consumers only incur the costs of each language they want to use.
  2. 個別のメタデータ: 各サテライト パッケージには、専用の .nuspec ファイルがあり、そのため、専用のローカライズされたメタデータがあります。Separate metadata: Each satellite package has its own .nuspec file and thus its own localized metadata because. これにより、一部のコンシューマーが、ローカライズされた用語で nuget.org を検索することで、より簡単にパッケージを検索できます。This can allow some consumers to find packages more easily by searching nuget.org with localized terms.
  3. 切り離されたリリース: サテライト アセンブリは、すべて一度にではなく時間の経過と共にリリースできるので、ローカライズ作業を分散することができます。Decoupled releases: Satellite assemblies can be released over time, rather than all at once, allowing you to spread out your localization efforts.

ただし、サテライト パッケージには、次の固有の一連のデメリットがあります。However, satellite packages have their own set of disadvantages:

  1. 煩雑さ: 1 つのパッケージの代わりに、多くのパッケージがあるので、nuget.org で検索結果が煩雑になり、Visual Studio プロジェクト内で参照の一覧が長くなる可能性があります。Clutter: Instead of a single package, you have many packages that can lead to cluttered search results on nuget.org and a long list of references in a Visual Studio project.
  2. 厳密な規則Strict conventions. サテライト パッケージは、規則に厳密に従う必要があります。そうしないと、ローカライズされたバージョンは正しく取得されません。Satellite packages must follow the conventions exactly or the localized versions won't be picked up properly.
  3. バージョン管理: 各サテライト パッケージは、プライマリ パッケージと正確なバージョンの依存関係を持っている必要があります。Versioning: Each satellite package must have an exact version dependency on the primary package. つまり、プライマリ パッケージを更新した場合、リソースを変更しない場合でもすべてのサテライト パッケージも更新する必要があります。This means that updating the primary package may require updating all satellite packages as well, even if the resources didn't change.