Dela via

Skapa lokaliserade NuGet-paket

Det finns två sätt att skapa lokaliserade versioner av ett bibliotek:

  1. Inkludera alla lokaliserade resurssammansättningar i ett enda paket.
  2. Skapa separata lokaliserade satellitpaket genom att följa en strikt uppsättning konventioner.

Båda metoderna har sina fördelar och nackdelar, enligt beskrivningen i följande avsnitt.

Lokaliserade resurssammansättningar i ett enda paket

Att inkludera lokaliserade resurssammansättningar i ett enda paket är vanligtvis den enklaste metoden. Det gör du genom att skapa mappar inom lib för andra språk som stöds än standardpaketet (antas vara en-us). I dessa mappar kan du placera resurssammansättningar och lokaliserade IntelliSense XML-filer.

Följande mappstruktur stöder till exempel tyska (de), italienska (den), japanska (ja), ryska (ru), kinesiska (förenklad) (zh-Hans) och kinesiska (traditionell) (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

Du kan se att alla språk visas under målramverksmappen net40 . Om du stöder flera ramverk har du en mapp under lib för varje variant.

Med dessa mappar på plats refererar du sedan till alla filer i :.nuspec

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

Ett exempelpaket som använder den här metoden är Microsoft.Data.OData 5.4.0.

Fördelar och nackdelar (lokaliserade resurssammansättningar)

Paketering av alla språk i ett enda paket har några nackdelar:

  1. Delade metadata: Eftersom ett NuGet-paket bara kan innehålla en enda .nuspec fil kan du bara ange metadata för ett enda språk. Det innebär att NuGet inte har stöd för lokaliserade metadata.
  2. Paketstorlek: Beroende på hur många språk du stöder kan biblioteket bli betydligt stort, vilket gör att installationen och återställningen av paketet blir långsammare.
  3. Samtidiga versioner: För att kunna paketera lokaliserade filer i ett enda paket måste du frigöra alla tillgångar i paketet samtidigt, i stället för att kunna frigöra varje lokalisering separat. Dessutom kräver alla uppdateringar av en lokalisering en ny version av hela paketet.

Men det har också några fördelar:

  1. Enkelhet: Paketkonsumenterna får alla språk som stöds i en enda installation i stället för att behöva installera varje språk separat. Ett enda paket är också enklare att hitta på nuget.org.
  2. Kopplade versioner: Eftersom alla resurssammansättningar finns i samma paket som den primära sammansättningen, delar de alla samma versionsnummer och riskerar inte att bli felaktigt frikopplade.

Lokaliserade satellitpaket

I likhet med hur .NET Framework stöder satellitsammansättningar separerar den här metoden lokaliserade resurser och IntelliSense XML-filer i satellitpaket.

Gör så här: ditt primära paket använder namngivningskonventionen {identifier}.{version}.nupkg och innehåller sammansättningen för standardspråket (till exempel en-US). Skulle till exempel ContosoUtilities.1.0.0.nupkg innehålla följande struktur:

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

En satellitsammansättning använder sedan namngivningskonventionen {identifier}.{language}.{version}.nupkg, till exempel ContosoUtilities.de.1.0.0.nupkg. Identifieraren måste exakt matcha det primära paketets.

Eftersom det här är ett separat paket har det en egen .nuspec fil som innehåller lokaliserade metadata. Tänk på att språket i .nuspecmåste matcha det som används i filnamnet.

Satellitsammansättningen måste också deklarera en exakt version av det primära paketet som ett beroende med hjälp av [] versionskommentationen (se Paketversionshantering). Du måste till exempel deklarera ett beroende av ContosoUtilities.1.0.0.nupkg genom att använda notationen [1.0.0]. Satellitpaketet kan naturligtvis ha ett annat versionsnummer än det primära paketet.

Satellitpaketets struktur måste sedan innehålla resurssammansättningen och XML IntelliSense-filen i en undermapp som matchar {language} i paketfilens namn:

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

Obs! Om inte specifika subkulturer som ja-JP är nödvändiga ska du alltid använda språkidentifieraren på högre nivå, till exempel ja.

I en satellitsammansättning känner NuGet bara igen de filer i mappen som matchar {language} i filnamnet. Alla andra ignoreras.

När alla dessa konventioner uppfylls identifierar NuGet paketet som ett satellitpaket och installerar de lokaliserade filerna i det primära paketets lib mapp, som om de ursprungligen hade paketerats. Om du avinstallerar satellitpaketet tas filerna bort från samma mapp.

Du skulle skapa ytterligare satellitsammansättningar på samma sätt för varje språk som stöds. Ett exempel är att undersöka uppsättningen med ASP.NET MVC-paket:

Sammanfattning av obligatoriska konventioner

  • Det primära paketet måste namnges {identifier}.{version}.nupkg
  • Ett satellitpaket måste namnges {identifier}.{language}.{version}.nupkg
  • Ett satellitpaket .nuspec måste ange sitt språk för att matcha filnamnet.
  • Ett satellitpaket måste deklarera ett beroende av en exakt version av huvudpaketet med hjälp av [] notationen i filen .nuspec. Intervall stöds inte.
  • Ett satellitpaket måste placera filer i mappen lib\[{framework}\]{language} som exakt matchar {language} i filnamnet.

Fördelar och nackdelar (satellitpaket)

Att använda satellitpaket har några fördelar:

  1. Paketstorlek: Det övergripande fotavtrycket för det primära paketet minimeras och konsumenterna debiteras endast kostnaderna för varje språk som de vill använda.
  2. Separata metadata: Varje satellitpaket har en egen .nuspec fil och därmed egna lokaliserade metadata. Detta kan göra det enklare för vissa konsumenter att hitta paket genom att söka nuget.org med lokaliserade termer.
  3. Frikopplade utgåvor: Satellitsammansättningar kan släppas över tid, i stället för alla på en gång, så att du kan sprida ut dina lokaliseringsinsatser.

Satellitpaket har dock en egen uppsättning nackdelar:

  1. Röra: I stället för ett enda paket har du flera paket som kan leda till oorganiserade sökresultat på nuget.org och en lång lista med referenser i ett Visual Studio-projekt.
  2. Strikta konventioner. Satellitpaket måste följa konventionerna exakt, annars hämtas inte de lokaliserade versionerna korrekt.
  3. Versionshantering: Varje satellitpaket måste ha ett exakt versionsberoende för det primära paketet. Det innebär att uppdatering av det primära paketet kan kräva uppdatering av alla satellitpaket också, även om resurserna inte har ändrats.