Erstellen lokalisierter NuGet-PaketeCreating localized NuGet packages

Es gibt zwei Methoden zum Erstellen lokalisierter Versionen einer Bibliothek:There are two ways to create localized versions of a library:

  1. Einschließen aller lokalisierten Ressourcenassemblys in ein einzelnes Paket.Include all localized resources assemblies in a single package.
  2. Erstellen einzelner lokalisierter Satellitenassemblys durch Befolgen einiger strikter Konventionen.Create separate localized satellite packages by following a strict set of conventions.

Beide Methoden haben ihre Vor- und Nachteile, wie in folgenden Abschnitten beschrieben.Both methods have their advantages and disadvantages, as described in the following sections.

Lokalisierte Ressourcenassemblys in einem einzelnen PaketLocalized resource assemblies in a single package

In der Regel ist es die einfachste Methode, alle lokalisierten Ressourcenassemblys in ein Paket einzuschließen.Including localized resource assemblies in a single package is typically the simplest approach. Dafür erstellen Sie Ordner für die unterstützten Sprachen in lib, die nicht der Standardsprache des Pakets entsprechen (es wird davon ausgegangen, dass die Standardsprache en-US ist).To do this, create folders within lib for supported language other than the package default (assumed to be en-us). In diesen Ordnern können Sie die Ressourcenassemblys und die lokalisierten XML-Dateien von IntelliSense platzieren.In these folders you can place resource assemblies and localized IntelliSense XML files.

Beispielsweise unterstützt die folgende Ordnerstruktur die Sprachen Deutsch (de), Italienisch (it), Japanisch (ja), Russisch (ru), Chinesisch (vereinfacht) (zh-Hans) und Chinesisch (traditionell) (zh-Hant):For example, the following folder structure supports, German (de), Italian (it), Japanese (ja), Russian (ru), Chinese (Simplified) (zh-Hans), and Chinese (Traditional) (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

Beachten Sie, dass alle Sprachen unter dem Zielframeworkordner net40 aufgelistet sind.You can see that the languages are all listed underneath the net40 target framework folder. Wenn Sie mehrere Frameworks unterstützen, verfügen Sie unter lib über einen Ordner für jedes Framework.If you're supporting multiple frameworks, then you have a folder under lib for each variant.

Mit diesen Ordnern verweisen Sie in .nuspec auf alle Dateien:With these folders in place, you then reference all the files in your .nuspec:

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

Ein Beispielpaket, das diese Vorgehensweise verwendet, ist Microsoft.Data.OData 5.4.0.One example package that uses this approach is Microsoft.Data.OData 5.4.0.

Vor- und Nachteile (lokalisierte Ressourcenassemblys)Advantages and disadvantages (localized resource assemblies)

Das Bündeln aller Sprachen in ein Paket hat einige Nachteile:Bundling all languages in a single package has a few disadvantages:

  1. Freigegebene Metadaten: Da ein NuGet-Paket nur eine einzige .nuspec-Datei enthalten kann, können Sie nur Metadaten für eine Sprache angeben.Shared metadata: Because a NuGet package can only contain a single .nuspec file, you can provide metadata for only a single language. Der Grund dafür ist, dass NuGet derzeit lokalisierte Metadaten nicht unterstützt.That is, NuGet does not present support localized metadata.
  2. Paketgröße: Abhängig von der Anzahl der Sprachen, die Sie unterstützen, kann die Bibliothek eine beträchtliche Größe erreichen, wodurch das Installieren und Wiederherstellen des Pakets verlangsamt wird.Package size: Depending on the number of languages you support, the library can become considerably large, which slows installing and restoring the package.
  3. Gleichzeitige Veröffentlichung: Das Bündeln lokalisierter Dateien in ein einzelnes Paket erfordert, dass alle Objekte in dem Paket gleichzeitig veröffentlicht werden. Sie können die Lokalisierungen nicht einzeln veröffentlichen.Simultaneous releases: Bundling localized files into a single package requires that you release all assets in that package simultaneously, rather than being able to release each localization separately. Weiterhin erfordert jedes Update einer Lokalisierung eine neue Version des gesamten Pakets.Furthermore, any update to any one localization requires a new version of the entire package.

Dennoch hat diese Methode auch Vorteile:However, it also has a few benefits:

  1. Einfachheit: Benutzer des Pakets erhalten mit einer Installation alle unterstützten Sprachen und müssen nicht jede Sprache einzeln installieren.Simplicity: Consumers of the package get all supported languages in a single install, rather than having to install each language separately. Ein einzelnes Paket ist auf nuget.org auch einfacher zu finden.A single package is also easier to find on nuget.org.
  2. Gekoppelte Versionen: Da sich alle Ressourcenassemblys im gleichen Paket wie die primäre Assembly befinden, teilen sie dieselbe Versionsnummer, und es besteht kein Risiko, dass sie fälschlicherweise voneinander entkoppelt werden.Coupled versions: Because all of the resource assemblies are in the same package as the primary assembly, they all share the same version number and don't run a risk of getting erroneously decoupled.

Lokalisierte SatellitenpaketeLocalized satellite packages

Genauso wie .NET Framework Satellitenassemblys unterstützt, trennt diese Methode die lokalisierten Ressourcen und XML-Dateien von IntelliSense in Satellitenpakete.Similar to how .NET Framework supports satellite assemblies, this method separates localized resources and IntelliSense XML files into satellite packages.

Dafür benutzt Ihr primäres Paket die Namenskonvention {identifier}.{version}.nupkg und enthält die Assembly für die Standardsprache (z.B. en-US).Do to this, your primary package uses the naming convention {identifier}.{version}.nupkg and contains the assembly for the default language (such as en-US). Zum Beispiel enthält ContosoUtilities.1.0.0.nupkg die folgende Struktur:For example, ContosoUtilities.1.0.0.nupkg would contain the following structure:

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

Eine Satellitenassembly nutzt dann die Namenskonvention {identifier}.{language}.{version}.nupkg, wie z.B. ContosoUtilities.de.1.0.0.nupkg.A satellite assembly then uses the naming convention {identifier}.{language}.{version}.nupkg, such as ContosoUtilities.de.1.0.0.nupkg. Der Bezeichner muss genau mit dem des primären Pakets übereinstimmen.The identifier must exactly match that of the primary package.

Da es sich um ein separates Paket handelt, verfügt es über eine eigene .nuspec-Datei, die lokalisierte Metadaten enthält.Because this is a separate package, it has its own .nuspec file that contains localized metadata. Beachten Sie, dass die Sprache in .nuspec der im Dateinamen angegebenen Sprache entsprechen muss.Be mindful that the language in the .nuspec must match the one used in the filename.

Die Satellitenassembly muss, mithilfe der []-Versionsnotation (siehe Package versioning (Versionierung von Paketen)), auch eine genaue Version des primären Pakets als Abhängigkeit deklarieren.The satellite assembly must also declare an exact version of the primary package as a dependency, using the [] version notation (see Package versioning). Beispielsweise muss ContosoUtilities.de.1.0.0.nupkg durch die Notation [1.0.0] eine Abhängigkeit von ContosoUtilities.1.0.0.nupkg deklarieren.For example, ContosoUtilities.de.1.0.0.nupkg must declare a dependency on ContosoUtilities.1.0.0.nupkg using the [1.0.0] notation. Die Versionsnummer des Satellitenpakets kann auch von der des primären Pakets abweichen.The satellite package can, of course, have a different version number than the primary package.

In diesem Fall muss die Struktur des Satellitenpakets die Ressourcenassembly und die XML-Datei von IntelliSense in einem Unterordner enthalten, dessen Name {language} im Paketdateinamen entspricht:The satellite package's structure must then include the resource assembly and XML IntelliSense file in a subfolder that matches {language} in the package filename:

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

Hinweis: Sofern keine spezifischen Untergruppen wie ja-JP benötigt werden, können Sie immer übergeordnete Sprachbezeichner wie ja verwenden.Note: unless specific subcultures such as ja-JP are necessary, always use the higher level language identifier, like ja.

NuGet erkennt in Satellitenassemblys nur die Dateien im Ordner, die {language} im Dateinamen entsprechen.In a satellite assembly, NuGet will recognize only those files in the folder that matches the {language} in the filename. Alle anderen werden ignoriert.All others are ignored.

Wenn all diese Konventionen erfüllt sind, erkennt NuGet das Paket als Satellitenpaket und installiert die lokalisierten Dateien im Ordner lib des primären Pakets, so als wären sie ursprünglich gebündelt gewesen.When all of these conventions are met, NuGet will recognize the package as a satellite package and install the localized files into the primary package's lib folder, as if they had been originally bundled. Beim Deinstallieren des Satellitenpakets werden dessen Dateien aus demselben Ordner entfernt.Uninstalling the satellite package will remove its files from that same folder.

Sie können diese Methode zum Erstellen von zusätzlichen Satellitenassemblys in sämtlichen unterstützten Sprachen nutzen.You would create additional satellite assemblies in the same way for each supported language. Weitere Beispiele finden Sie in diesen ASP.NET MVC-Paketen:For an example, examine the set of ASP.NET MVC packages:

Zusammenfassung der erforderlichen KonventionenSummary of required conventions

  • Das primäre Paket muss im Format {identifier}.{version}.nupkg benannt sein.Primary package must be named {identifier}.{version}.nupkg
  • Satellitenpakete müssen im Format {identifier}.{language}.{version}.nupkg benannt sein.A satellite package must be named {identifier}.{language}.{version}.nupkg
  • Die Datei .nuspec eines Satellitenpakets muss die Sprache entsprechend dem Dateinamen angeben.A satellite package's .nuspec must specify its language to match the filename.
  • Ein Satellitenpaket muss eine Abhängigkeit auf einer exakten Version des primären Pakets mithilfe der Notation [] in der .nuspec-Datei deklarieren.A satellite package must declare a dependency on an exact version of the primary using the [] notation in its .nuspec file. Bereiche werden nicht unterstützt.Ranges are not supported.
  • Satellitenpakete müssen Dateien im Ordner lib\[{framework}\]{language} platzieren, die genau {language} im Dateinamen entsprechen.A satellite package must place files in the lib\[{framework}\]{language} folder that exactly matches {language} in the filename.

Vor- und Nachteile (Satellitenpakete)Advantages and disadvantages (satellite packages)

Die Verwendung von Satellitenpaketen hat einige Vorteile:Using satellite packages has a few benefits:

  1. Paketgröße: Der gesamte Speicherbedarf des primären Pakets wird verringert, und für Benutzer fallen nur die Kosten der Sprachen an, die sie auch verwenden wollen.Package size: The overall footprint of the primary package is minimized, and consumers only incur the costs of each language they want to use.
  2. Separate Metadaten: Jedes Satellitenpaket hat seine eigene .nuspec-Datei, und demnach auch seine eigenen lokalisierten Metadaten.Separate metadata: Each satellite package has its own .nuspec file and thus its own localized metadata because. Dadurch wird Benutzern ermöglicht, Pakete leichter zu finden, da sie auf nuget.org mit lokalisierten Begriffen suchen können.This can allow some consumers to find packages more easily by searching nuget.org with localized terms.
  3. Ungebundene Releases: Satellitenassemblys können nach und nach veröffentlicht werden, wodurch Sie den Aufwand für Ihre Lokalisierung verteilen können.Decoupled releases: Satellite assemblies can be released over time, rather than all at once, allowing you to spread out your localization efforts.

Satellitenpakete haben jedoch ihre eigenen Nachteile:However, satellite packages have their own set of disadvantages:

  1. Unübersichtliche: Anstelle eines einzelnen Pakets haben Sie viele Pakete, was zu unübersichtlichen Suchergebnissen auf nuget.org und einer langen Liste von Verweisen in einem Visual Studio-Projekt führen kann.Clutter: Instead of a single package, you have many packages that can lead to cluttered search results on nuget.org and a long list of references in a Visual Studio project.
  2. Strenge Konventionen:Strict conventions. Satellitenpakete müssen die Konventionen strikt befolgen, sonst werden die lokalisierten Versionen nicht richtig abgerufen.Satellite packages must follow the conventions exactly or the localized versions won't be picked up properly.
  3. Versionierung: Jedes Satellitenpaket benötigt eine bestimmte Versionsabhängigkeit vom primären Paket.Versioning: Each satellite package must have an exact version dependency on the primary package. Das bedeutet, dass ein Update des primären Pakets auch die Aktualisierung aller Satellitenpakete erfordert, selbst wenn an den Ressourcen nichts geändert wurde.This means that updating the primary package may require updating all satellite packages as well, even if the resources didn't change.