ローカライズされた NuGet パッケージの作成

ライブラリのローカライズされたバージョンを作成するには、次の 2 つの方法があります。

1. ローカライズされたすべてのリソース アセンブリを 1 つのパッケージに含めます。
2. 厳密な規則のセットに従って、ローカライズされたサテライト パッケージを個別に作成します。

次のセクションで説明するように、どちらの方法にも長所と短所があります。

1 つのパッケージ内のローカライズされたリソース アセンブリ

ローカライズされたリソース アセンブリを 1 つのパッケージに含めると、通常は最も簡単な方法です。 これを行うには、パッケージの既定値 (en-us) 以外のサポートされている言語のフォルダーを lib 内に作成します。 これらのフォルダーには、リソース アセンブリとローカライズされた IntelliSense XML ファイルを配置できます。

たとえば、次のフォルダー構造では、ドイツ語 (de)、イタリア語 (it)、日本語 (ja)、ロシア語 (ru)、中国語 (簡体字) (zh-Hans)、および中国語 (繁体字) (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 ターゲット フレームワーク フォルダーの下に一覧表示されていることがわかります。 複数のフレームワークを サポートしている場合は、各バリアントの lib の下にフォルダーがあります。

これらのフォルダーを配置したら、 .nuspec内のすべてのファイルを参照します。

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

このアプローチを使用するパッケージの例の 1 つは 、Microsoft.Data.OData 5.4.0 です。

長所と短所 (ローカライズされたリソース アセンブリ)

すべての言語を 1 つのパッケージにバンドルすると、いくつかの欠点があります。

1. 共有メタデータ: NuGet パッケージには 1 つの .nuspec ファイルのみを含めることができるため、メタデータを提供できるのは 1 つの言語のみです。 つまり、NuGet はローカライズされたメタデータをサポートしていません。
2. パッケージ サイズ: サポートする言語の数によっては、ライブラリが大幅に大きくなる可能性があり、パッケージのインストールと復元が遅くなります。
3. 同時リリース: ローカライズされたファイルを 1 つのパッケージにバンドルするには、各ローカライズを個別にリリースするのではなく、そのパッケージ内のすべての資産を同時にリリースする必要があります。 さらに、任意のローカライズに対する更新には、パッケージ全体の新しいバージョンが必要です。

ただし、次のような利点もあります。

1. 簡略化: パッケージのコンシューマーは、各言語を個別にインストールする必要なく、サポートされているすべての言語を 1 回のインストールで取得します。 1 つのパッケージも、nuget.org で見つけやすくなります。
2. 結合バージョン: すべてのリソース アセンブリはプライマリ アセンブリと同じパッケージ内にあるため、それらはすべて同じバージョン番号を共有し、誤って切り離されるリスクを実行しません。

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

.NET Framework がサテライト アセンブリをサポートする方法と同様に、このメソッドはローカライズされたリソースと IntelliSense XML ファイルをサテライト パッケージに分離します。

これを行うには、プライマリ パッケージで名前付け規則 {identifier}.{version}.nupkg を使用し、既定の言語 (en-USなど) のアセンブリが含まれています。 たとえば、 ContosoUtilities.1.0.0.nupkg には次の構造が含まれます。

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

サテライト アセンブリでは、{identifier}.{language}.{version}.nupkgなどの名前付け規則ContosoUtilities.de.1.0.0.nupkgが使用されます。 識別子は、プライマリ パッケージの識別子と完全に一致する 必要があります 。

これは別のパッケージであるため、ローカライズされたメタデータを含む独自の .nuspec ファイルがあります。 .nuspec must の言語は、ファイル名で使用されている言語と一致していることに注意してください。

サテライト アセンブリでは、[] バージョン表記を使用して、プライマリ パッケージの正確なバージョンを依存関係として宣言する 必要もあります ( パッケージのバージョン管理を参照)。 たとえば、ContosoUtilities.de.1.0.0.nupkgは、ContosoUtilities.1.0.0.nupkg表記を使用して[1.0.0]への依存関係を宣言する必要があります。 サテライト パッケージは、もちろん、プライマリ パッケージとは異なるバージョン番号を持つことができます。

サテライト パッケージの構造は、リソース アセンブリと XML IntelliSense ファイルを、パッケージ ファイル名の {language} と一致するサブフォルダーに含める必要があります。

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

注: ja-JP などの特定のサブカルチャが必要な場合を除き、常に jaなどの上位レベルの言語識別子を使用します。

サテライト アセンブリでは、NuGet はファイル名のと一致するフォルダー内のファイル{language}認識します。 それ以外はすべて無視されます。

これらの規則がすべて満たされると、NuGet はパッケージをサテライト パッケージとして認識し、ローカライズされたファイルを最初にバンドルされたかのように、プライマリ パッケージの lib フォルダーにインストールします。 サテライト パッケージをアンインストールすると、その同じフォルダーからファイルが削除されます。

サポートされている言語ごとに、同じ方法で追加のサテライト アセンブリを作成します。 たとえば、ASP.NET MVC パッケージのセットを調べます。

• Microsoft.AspNet.Mvc (英語のプライマリ)
• Microsoft.AspNet.Mvc.de (ドイツ語)
• Microsoft.AspNet.Mvc.ja (日本語)
• Microsoft.AspNet.Mvc.zh-Hans (中国語 (簡体字))
• Microsoft.AspNet.Mvc.zh-Hant (中国語 (繁体字))

必要な規則の概要

• プライマリ パッケージに名前を付ける必要がある {identifier}.{version}.nupkg
• サテライト パッケージに名前を付ける必要がある {identifier}.{language}.{version}.nupkg
• サテライト パッケージの .nuspec は、ファイル名と一致するように言語を指定する必要があります。
• サテライト パッケージでは、 .nuspec ファイルの [] 表記を使用して、プライマリの正確なバージョンへの依存関係を宣言する必要があります。 範囲はサポートされていません。
• サテライト パッケージは、ファイル名内のlib\[{framework}\]{language}と完全に一致するファイルを {language} フォルダーに配置する必要があります。

長所と短所 (サテライト パッケージ)

サテライト パッケージの使用には、いくつかの利点があります。

1. パッケージ サイズ: プライマリ パッケージの全体的なフットプリントは最小限に抑えられ、コンシューマーは使用する各言語のコストのみが発生します。
2. 個別のメタデータ: 各サテライト パッケージには、独自の .nuspec ファイルと、独自のローカライズされたメタデータがあります。 これにより、一部のコンシューマーは、ローカライズされた用語で nuget.org を検索することで、パッケージをより簡単に見つけることができます。
3. 分離されたリリース: サテライト アセンブリは、一度にすべてではなく時間の経過と同時にリリースできるため、ローカライズ作業を分散できます。

ただし、サテライト パッケージには独自の欠点があります。

1. 散らかった状態: 単一のパッケージではなく、多数のパッケージがあることで、nuget.org の検索結果が散らかった状態になり、Visual Studio プロジェクト内で参照が長いリストになってしまう可能性があります。
2. 厳密な規則。 サテライト パッケージは規則に正確に従う必要があります。そうしないと、ローカライズされたバージョンが正しく取得されません。
3. バージョン管理: 各サテライト パッケージには、プライマリ パッケージに対する正確なバージョンの依存関係が必要です。 つまり、リソースが変更されなかった場合でも、プライマリ パッケージを更新するには、すべてのサテライト パッケージの更新が必要になる場合があります。