Vytváření lokalizovaných balíčků NuGet

Lokalizované verze knihovny můžete vytvořit dvěma způsoby:

1. Zahrňte všechna lokalizovaná sestavení prostředků do jednoho balíčku.
2. Vytvořte samostatné lokalizované satelitní balíčky podle striktní sady konvencí.

Obě metody mají své výhody a nevýhody, jak je popsáno v následujících částech.

Lokalizovaná sestavení prostředků v jednom balíčku

Zahrnutí lokalizovaných sestavení prostředků do jednoho balíčku je obvykle nejjednodušším přístupem. Uděláte to tak, že vytvoříte složky v lib rámci jiného podporovaného jazyka než výchozího balíčku (předpokládá se, že se jedná o en-us). V těchto složkách můžete umístit sestavení prostředků a lokalizované soubory INTELLISense XML.

Například následující struktura složek podporuje němčinu (de), italštinu (it), japonštinu (ja), ruštinu (ru), čínštinu (zjednodušenou) (zh-Hans) a čínštinu (tradiční) (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

Vidíte, že všechny jazyky jsou uvedené pod cílovou složkou net40 architektury. Pokud podporujete více architektur, máte pro každou variantu složku lib .

S těmito složkami pak budete odkazovat na všechny soubory ve svém .nuspec:

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

Příkladem balíčku, který tento přístup používá, je Microsoft.Data.OData 5.4.0.

Výhody a nevýhody (lokalizovaná sestavení prostředků)

Sdružování všech jazyků v jednom balíčku má několik nevýhod:

1. Sdílená metadata: Protože balíček NuGet může obsahovat pouze jeden .nuspec soubor, můžete zadat metadata pouze pro jeden jazyk. To znamená, že NuGet nepodporuje lokalizovaná metadata.
2. Velikost balíčku: V závislosti na počtu jazyků, které podporujete, se knihovna může výrazně zvětšit, což zpomaluje instalaci a obnovení balíčku.
3. Souběžné verze: Zabalení lokalizovaných souborů do jednoho balíčku vyžaduje, abyste všechny prostředky v balíčku vydali současně, a ne aby bylo možné uvolnit každou lokalizaci samostatně. Kromě toho jakákoli aktualizace jakékoli lokalizace vyžaduje novou verzi celého balíčku.

Má ale také několik výhod:

1. Jednoduchost: Spotřebitelé balíčku získají všechny podporované jazyky v jedné instalaci, a nemusíte je instalovat samostatně. Jeden balíček je také jednodušší najít na nuget.org.
2. Párované verze: Vzhledem k tomu, že všechna sestavení prostředků jsou ve stejném balíčku jako primární sestavení, všechny sdílejí stejné číslo verze a nehroutí riziko chybného oddělení.

Lokalizované satelitní balíčky

Podobně jako rozhraní .NET Framework podporuje satelitní sestavení, tato metoda odděluje lokalizované prostředky a soubory XML technologie IntelliSense do satelitních balíčků.

K tomu váš primární balíček používá konvenci {identifier}.{version}.nupkg pojmenování a obsahuje sestavení pro výchozí jazyk (například en-US). Například ContosoUtilities.1.0.0.nupkg by obsahovala následující strukturu:

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

Satelitní sestavení pak používá konvenci {identifier}.{language}.{version}.nupkgpojmenování , například ContosoUtilities.de.1.0.0.nupkg. Identifikátor musí přesně odpovídat identifikátoru primárního balíčku.

Vzhledem k tomu, že se jedná o samostatný balíček, má vlastní .nuspec soubor, který obsahuje lokalizovaná metadata. Mějte na paměti, že jazyk v souboru .nuspecse musí shodovat s jazykem použitým v názvu souboru.

Satelitní sestavení musí také deklarovat přesnou verzi primárního balíčku jako závislost pomocí zápisu verze [] (viz správa verzí balíčku). Musí například ContosoUtilities.de.1.0.0.nupkg deklarovat závislost na ContosoUtilities.1.0.0.nupkg použití zápisu [1.0.0] . Satelitní balíček může mít samozřejmě jiné číslo verze než primární balíček.

Struktura satelitního balíčku pak musí obsahovat sestavení prostředků a soubor XML IntelliSense do podsložky, která odpovídá {language} názvu souboru balíčku:

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

Poznámka: Pokud nejsou ja-JP nutné konkrétní subkultuře, použijte vždy identifikátor jazyka vyšší úrovně, například ja.

V satelitním sestavení NuGet rozpozná pouze ty soubory ve složce, které odpovídají {language} názvu souboru. Všechny ostatní jsou ignorovány.

Když jsou splněny všechny tyto konvence, NuGet rozpozná balíček jako satelitní balíček a nainstaluje lokalizované soubory do složky primárního lib balíčku, jako by byly původně seskupené. Odinstalace satelitního balíčku odebere soubory ze stejné složky.

Pro každý podporovaný jazyk byste vytvořili další satelitní sestavení stejným způsobem. Podívejte se například na sadu balíčků ASP.NET MVC:

• Microsoft.AspNet.Mvc (primární angličtina)
• Microsoft.AspNet.Mvc.de (němčina)
• Microsoft.AspNet.Mvc.ja (japonština)
• Microsoft.AspNet.Mvc.zh-Hans (čínština (zjednodušená))
• Microsoft.AspNet.Mvc.zh-Hant (čínština (tradiční))

Souhrn požadovaných konvencí

• Primární balíček musí mít název {identifier}.{version}.nupkg
• Satelitní balíček musí být pojmenovaný. {identifier}.{language}.{version}.nupkg
• Satelitní balíček .nuspec musí určit jeho jazyk, aby odpovídal názvu souboru.
• Satelitní balíček musí deklarovat závislost na přesné verzi primárního souboru pomocí zápisu .nuspec []. Rozsahy nejsou podporovány.
• Satelitní balíček musí umístit soubory do lib\[{framework}\]{language} složky, která přesně odpovídá {language} názvu souboru.

Výhody a nevýhody (satelitní balíčky)

Používání satelitních balíčků má několik výhod:

1. Velikost balíčku: Celková stopa primárního balíčku je minimalizovaná a příjemci účtují pouze náklady na každý jazyk, který chtějí použít.
2. Samostatná metadata: Každý satelitní balíček má svůj vlastní .nuspec soubor a vlastní lokalizovaná metadata. To může některým příjemcům umožnit snadněji najít balíčky vyhledáváním nuget.org s lokalizovanými termíny.
3. Oddělené verze: Satelitní sestavení mohou být vydána v průběhu času, spíše než všechny najednou, což vám umožní rozprostřet lokalizační úsilí.

Satelitní balíčky ale mají vlastní sadu nevýhod:

1. Nepotřebné: Místo jednoho balíčku máte mnoho balíčků, které můžou vést k nepřehledným výsledkům hledání na nuget.org a dlouhému seznamu odkazů v projektu sady Visual Studio.
2. Striktní konvence. Satelitní balíčky musí přesně dodržovat konvence nebo lokalizované verze nebudou správně vyzvednuty.
3. Správa verzí: Každý satelitní balíček musí mít přesnou závislost na verzi primárního balíčku. To znamená, že aktualizace primárního balíčku může vyžadovat aktualizaci všech satelitních balíčků i v případě, že se prostředky nezměnily.