Freigeben über

Erstellen lokalisierter NuGet-Pakete

Es gibt zwei Möglichkeiten zum Erstellen lokalisierter Versionen einer Bibliothek:

  1. Schließen Sie alle lokalisierten Ressourcenassemblys in ein einzelnes Paket ein.
  2. Erstellen Sie separate lokalisierte Satellitenpakete, indem Sie einer strengen Reihe von Konventionen folgen.

Beide Methoden haben ihre Vor- und Nachteile, wie in den folgenden Abschnitten beschrieben.

Lokalisierte Ressourcen-Assemblies in einem einzigen Paket

Das Einschließen lokalisierter Ressourcenassemblys in einem einzelnen Paket ist in der Regel der einfachste Ansatz. Erstellen Sie dazu Ordner in lib für eine unterstützte Sprache, die nicht dem Standardpaket entspricht (vorausgesetzt, dass der Standard en-us ist). In diesen Ordnern können Sie Ressourcenassemblys und lokalisierte IntelliSense-XML-Dateien platzieren.

Die folgende Ordnerstruktur unterstützt z. B. Deutsch (de), Italienisch (it), Japanisch (ja), Russisch (ru), Chinesisch (vereinfacht) (zh-Hans) und Chinesisch (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

Sie können sehen, dass die Sprachen unter dem net40 Zielframeworkordner aufgelistet sind. Wenn Sie mehrere Frameworks unterstützen, haben Sie für jede Variante einen Ordner lib unter.

Wenn diese Ordner vorhanden sind, verweisen Sie dann auf alle Dateien in Ihrer .nuspecDatei:

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

Ein Beispielpaket, das diesen Ansatz verwendet, ist Microsoft.Data.OData 5.4.0.

Vor- und Nachteile (lokalisierte Ressourcenassemblys)

Das Bündeln aller Sprachen in einem einzelnen Paket hat einige Nachteile:

  1. Freigegebene Metadaten: Da ein NuGet-Paket nur eine einzelne .nuspec Datei enthalten kann, können Sie Metadaten nur für eine einzelne Sprache bereitstellen. Das heißt, NuGet unterstützt keine lokalisierten Metadaten.
  2. Paketgröße: Abhängig von der Anzahl der sprachen, die Sie unterstützen, kann die Bibliothek erheblich groß werden, wodurch die Installation und Wiederherstellung des Pakets verlangsamt wird.
  3. Gleichzeitige Versionen: Das Bündeln lokalisierter Dateien in ein einzelnes Paket erfordert, dass Sie alle Ressourcen in diesem Paket gleichzeitig freigeben, anstatt jede Lokalisierung separat freigeben zu können. Darüber hinaus erfordert jedes Update für jede Lokalisierung eine neue Version des gesamten Pakets.

Es hat jedoch auch einige Vorteile:

  1. Einfachheit: Verbraucher des Pakets erhalten alle unterstützten Sprachen in einer einzigen Installation, anstatt jede Sprache separat installieren zu müssen. Ein einzelnes Paket ist auch einfacher auf nuget.org zu finden.
  2. Gekoppelte Versionen: Da sich alle Ressourcenassemblys im selben Paket wie die primäre Assembly befinden, teilen sie alle die gleiche Versionsnummer und führen kein Risiko aus, versehentlich entkoppelt zu werden.

Lokalisierte Satellitenpakete

Ähnlich wie .NET Framework Satellitenassemblys unterstützt, trennt diese Methode lokalisierte Ressourcen und IntelliSense-XML-Dateien in Satellitenpakete.

Dazu verwendet Ihr primäres Paket die Benennungskonvention {identifier}.{version}.nupkg und enthält die Assembly für die Standardsprache (z. B. en-US). Beispielsweise würde ContosoUtilities.1.0.0.nupkg die folgende Struktur enthalten:

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

Eine Satellitenassembly verwendet dann die Benennungskonvention {identifier}.{language}.{version}.nupkg, z. B. ContosoUtilities.de.1.0.0.nupkg. Der Bezeichner muss genau mit dem des primären Pakets übereinstimmen.

Da es sich um ein separates Paket handelt, verfügt es über eine eigene .nuspec Datei, die lokalisierte Metadaten enthält. Achten Sie darauf, dass die Sprache in der .nuspecübereinstimmen muss mit der im Dateinamen verwendeten.

Die Satellitenassembly muss auch eine genaue Version des primären Pakets als Abhängigkeit deklarieren, wobei die [] Versionsnotation verwendet wird (siehe Paketversionsverwaltung). Beispielsweise muss ContosoUtilities.de.1.0.0.nupkg eine Abhängigkeit von ContosoUtilities.1.0.0.nupkg unter Verwendung der [1.0.0] Notation deklarieren. Das Satellitenpaket kann natürlich eine andere Versionsnummer haben als das primäre Paket.

Die Struktur des Satellitenpakets muss dann die Ressourcenassembly und die XML IntelliSense-Datei in einen Unterordner einschließen, der mit dem Paketdateinamen übereinstimmt {language} :

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

Hinweis: Wenn bestimmte Unterkulturen wie ja-JP erforderlich sind, verwenden Sie stets den Sprachbezeichner der höheren Ebene, wie ja.

In einer Satellitenassembly erkennt NuGet nur die Dateien im Ordner, die mit dem {language} Dateinamen übereinstimmen. Alle anderen werden ignoriert.

Wenn alle diese Konventionen erfüllt sind, erkennt NuGet das Paket als Satellitenpaket und installiert die lokalisierten Dateien im Ordner des primären Pakets lib , als wäre sie ursprünglich gebündelt. Durch die Deinstallation des Satellitenpakets werden die Dateien aus demselben Ordner entfernt.

Sie würden zusätzliche Satellitenassemblys auf die gleiche Weise für jede unterstützte Sprache erstellen. Untersuchen Sie beispielsweise den Satz von ASP.NET MVC-Paketen:

Zusammenfassung der erforderlichen Konventionen

  • Primäres Paket muss benannt werden {identifier}.{version}.nupkg
  • Ein Satellitenpaket muss benannt werden. {identifier}.{language}.{version}.nupkg
  • Die Sprache eines Satellitenpakets .nuspec muss mit dem Dateinamen übereinstimmen.
  • Ein Satellitenpaket muss eine Abhängigkeit von einer genauen Version des primären Pakets deklarieren, wobei die [] Schreibweise in der .nuspec Datei verwendet wird. Bereiche werden nicht unterstützt.
  • Ein Satellitenpaket muss Dateien in dem Ordner platzieren, dessen Name exakt mit dem Dateinamen übereinstimmt lib\[{framework}\]{language}{language}.

Vor- und Nachteile (Satellitenpakete)

Die Verwendung von Satellitenpaketen bietet einige Vorteile:

  1. Paketgröße: Der Gesamtbedarf des primären Pakets wird minimiert, und Verbraucher verursachen nur die Kosten für jede Sprache, die sie verwenden möchten.
  2. Separate Metadaten: Jedes Satellitenpaket verfügt über eine eigene .nuspec Datei und somit über eigene lokalisierte Metadaten. Dies kann es einigen Nutzern ermöglichen, Pakete einfacher zu finden, indem sie mit lokalisierten Begriffen auf nuget.org suchen.
  3. Entkoppelte Versionen: Satellitenassemblys können im Laufe der Zeit und nicht alle gleichzeitig freigegeben werden, sodass Sie Ihre Lokalisierungsbemühungen verteilen können.

Satellitenpakete haben jedoch eigene Nachteile:

  1. Clutter: Anstelle eines einzelnen Pakets haben Sie viele Pakete, die zu unübersichtlichen Suchergebnissen in nuget.org und einer langen Liste von Verweisen in einem Visual Studio-Projekt führen können.
  2. Strenge Konventionen. Satellitenpakete müssen den Konventionen entsprechen, oder die lokalisierten Versionen werden nicht ordnungsgemäß aufgenommen.
  3. Versionsverwaltung: Jedes Satellitenpaket muss eine genaue Versionsabhängigkeit vom primären Paket aufweisen. Dies bedeutet, dass das Aktualisieren des primären Pakets möglicherweise auch die Aktualisierung aller Satellitenpakete erfordert, auch wenn sich die Ressourcen nicht geändert haben.
  • Last updated on