Tworzenie zlokalizowanych pakietów NuGet

Istnieją dwa sposoby tworzenia zlokalizowanych wersji biblioteki:

1. Uwzględnij wszystkie zlokalizowane zestawy zasobów w jednym pakiecie.
2. Utwórz oddzielne zlokalizowane pakiety satelitarne, postępując zgodnie z rygorystycznym zestawem konwencji.

Obie metody mają swoje zalety i wady, jak opisano w poniższych sekcjach.

Zlokalizowane zestawy zasobów w jednym pakiecie

Uwzględnienie zlokalizowanych zestawów zasobów w jednym pakiecie jest zwykle najprostszym podejściem. W tym celu utwórz foldery w lib programie dla obsługiwanego języka innego niż domyślny pakiet (zakłada się, że jest to en-us). W tych folderach można umieścić zestawy zasobów i zlokalizowane pliki XML funkcji IntelliSense.

Na przykład następująca struktura folderów obsługuje język niemiecki (de), włoski (it), japoński (ja), rosyjski (ru), chiński (uproszczony) (zh-Hans) i chiński (tradycyjny) (zh-Tsunami):

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

Widać, że wszystkie języki znajdują się poniżej folderu platformy net40 docelowej. Jeśli obsługujesz wiele platform, masz folder w obszarze lib dla każdego wariantu.

Po zainstalowaniu tych folderów odwołujesz się do wszystkich plików w pliku .nuspec:

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

Jednym z przykładowych pakietów korzystających z tego podejścia jest Microsoft.Data.OData 5.4.0.

Zalety i wady (zlokalizowane zestawy zasobów)

Łączenie wszystkich języków w jednym pakiecie ma kilka wad:

1. Udostępnione metadane: ponieważ pakiet NuGet może zawierać tylko jeden .nuspec plik, można podać metadane tylko dla jednego języka. Oznacza to, że pakiet NuGet nie obsługuje zlokalizowanych metadanych.
2. Rozmiar pakietu: w zależności od liczby obsługiwanych języków biblioteka może stać się znacznie duża, co spowalnia instalowanie i przywracanie pakietu.
3. Równoczesne wydania: tworzenie pakietów zlokalizowanych plików w jednym pakiecie wymaga jednoczesnego zwolnienia wszystkich zasobów w tym pakiecie zamiast zwalniania poszczególnych lokalizacji. Ponadto każda aktualizacja dowolnej lokalizacji wymaga nowej wersji całego pakietu.

Jednak ma również kilka korzyści:

1. Prostota: Konsumenci pakietu uzyskują wszystkie obsługiwane języki w jednej instalacji, zamiast instalować każdy język oddzielnie. Pojedynczy pakiet jest również łatwiejszy do znalezienia w nuget.org.
2. Wersje w połączeniu: ze względu na to, że wszystkie zestawy zasobów znajdują się w tym samym pakiecie co podstawowy zestaw, wszystkie mają ten sam numer wersji i nie ryzykują błędnego oddzielenia.

Zlokalizowane pakiety satelitarne

Podobnie jak program .NET Framework obsługuje zestawy satelitarne, ta metoda oddziela zlokalizowane zasoby i pliki XML funkcji IntelliSense do pakietów satelitarnych.

W tym celu pakiet podstawowy używa konwencji {identifier}.{version}.nupkg nazewnictwa i zawiera zestaw dla języka domyślnego (na przykład en-US). Na przykład ContosoUtilities.1.0.0.nupkg może zawierać następującą strukturę:

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

Następnie zestaw satelitarny używa konwencji {identifier}.{language}.{version}.nupkgnazewnictwa , takiej jak ContosoUtilities.de.1.0.0.nupkg. Identyfikator musi być dokładnie zgodny z pakietem podstawowym.

Ponieważ jest to oddzielny pakiet, ma własny .nuspec plik zawierający zlokalizowane metadane. Należy pamiętać, że język w pliku .nuspec musi być zgodny z językiem używanym w nazwie pliku.

Zestaw satelitarny musi również zadeklarować dokładną wersję pakietu podstawowego jako zależność przy użyciu notacji wersji [] (zobacz Przechowywanie wersji pakietu). Na przykład ContosoUtilities.de.1.0.0.nupkg należy zadeklarować zależność od ContosoUtilities.1.0.0.nupkg użycia [1.0.0] notacji. Pakiet satelitarny może oczywiście mieć inny numer wersji niż pakiet podstawowy.

Struktura pakietu satelitarnego musi następnie zawierać zestaw zasobów i plik XML IntelliSense w podfolderze zgodnym {language} z nazwą pliku pakietu:

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

Uwaga: o ile nie są wymagane określone podkultury, takie jak są konieczne, zawsze używaj identyfikatora języka wyższego poziomu, takiego jak ja-JP ja.

W zestawie satelitarnym NuGet rozpozna tylko te pliki w folderze, który pasuje do {language} nazwy pliku. Wszystkie inne są ignorowane.

Po spełnieniu wszystkich tych konwencji nuGet rozpozna pakiet jako pakiet satelitarny i zainstaluje zlokalizowane pliki w folderze pakietu lib podstawowego, tak jakby zostały pierwotnie dołączone. Odinstalowanie pakietu satelitarnego spowoduje usunięcie jego plików z tego samego folderu.

Dodatkowe zestawy satelitarne można utworzyć w taki sam sposób dla każdego obsługiwanego języka. Na przykład sprawdź zestaw pakietów ASP.NET MVC:

• Microsoft.AspNet.Mvc (angielski podstawowy)
• Microsoft.AspNet.Mvc.de (niemiecki)
• Microsoft.AspNet.Mvc.ja (japoński)
• Microsoft.AspNet.Mvc.zh-Hans (chiński (uproszczony))
• Microsoft.AspNet.Mvc.zh-Gnu (chiński (tradycyjny))

Podsumowanie wymaganych konwencji

• Pakiet podstawowy musi mieć nazwę {identifier}.{version}.nupkg
• Pakiet satelitarny musi mieć nazwę {identifier}.{language}.{version}.nupkg
• Pakiet satelitarny .nuspec musi określać jego język, aby był zgodny z nazwą pliku.
• Pakiet satelitarny musi zadeklarować zależność od dokładnej wersji podstawowej przy użyciu notacji [] w pliku .nuspec . Zakresy nie są obsługiwane.
• Pakiet satelitarny musi umieszczać pliki w lib\[{framework}\]{language} folderze, który dokładnie pasuje {language} do nazwy pliku.

Zalety i wady (pakiety satelitarne)

Korzystanie z pakietów satelitarnych ma kilka korzyści:

1. Rozmiar pakietu: ogólny ślad pakietu podstawowego jest zminimalizowany, a konsumenci generują tylko koszty każdego języka, którego chcą użyć.
2. Oddzielne metadane: każdy pakiet satelitarny ma własny .nuspec plik, a tym samym własne zlokalizowane metadane. Dzięki temu niektórzy użytkownicy mogą łatwiej wyszukiwać pakiety, wyszukując nuget.org przy użyciu zlokalizowanych terminów.
3. Oddzielone wydania: Zestawy satelitarne mogą być zwalniane w czasie, a nie jednocześnie, co pozwala na rozłożenie wysiłków związanych z lokalizacją.

Jednak pakiety satelitarne mają własny zestaw wad:

1. Clutter: Zamiast pojedynczego pakietu masz wiele pakietów, które mogą prowadzić do zaśmieconych wyników wyszukiwania na nuget.org i długiej listy odwołań w projekcie programu Visual Studio.
2. Ścisłe konwencje. Pakiety satelitarne muszą być zgodne z konwencjami dokładnie lub zlokalizowane wersje nie zostaną prawidłowo odebrane.
3. Przechowywanie wersji: każdy pakiet satelitarny musi mieć dokładną zależność wersji od pakietu podstawowego. Oznacza to, że aktualizacja pakietu podstawowego może również wymagać aktualizacji wszystkich pakietów satelitarnych, nawet jeśli zasoby nie uległy zmianie.