Création de packages NuGet localisésCreating localized NuGet packages

Il existe deux façons de créer des versions localisées d’une bibliothèque :There are two ways to create localized versions of a library:

  1. Incluez tous les assemblys de ressources localisés dans un package unique.Include all localized resources assemblies in a single package.
  2. Créez des packages satellites localisés distincts en suivant un ensemble strict de conventions.Create separate localized satellite packages by following a strict set of conventions.

Les deux méthodes ont leurs avantages et leurs inconvénients, comme décrit dans les sections suivantes.Both methods have their advantages and disadvantages, as described in the following sections.

Assemblys de ressources localisés dans un package uniqueLocalized resource assemblies in a single package

L’inclusion des assemblys de ressources localisés dans un package unique constitue généralement l’approche la plus simple.Including localized resource assemblies in a single package is typically the simplest approach. Pour cela, créez des dossiers dans lib pour la langue prise en charge autre que celle par défaut du package (supposée être en-us).To do this, create folders within lib for supported language other than the package default (assumed to be en-us). Dans ces dossiers, vous pouvez placer des assemblys de ressources et des fichiers XML IntelliSense localisés.In these folders you can place resource assemblies and localized IntelliSense XML files.

Par exemple, la structure de dossiers suivante prend en charge l’allemand (de), l’italien (it), le japonais (ja), le russe (ru), le chinois simplifié (zh-Hans) et le chinois traditionnel (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

Vous pouvez voir que les langues sont toutes répertoriées sous le dossier de la version cible de .Net Framework net40.You can see that the languages are all listed underneath the net40 target framework folder. Si vous prenez en charge plusieurs versions, vous avez un dossier sous lib pour chacune d’elles.If you're supporting multiple frameworks, then you have a folder under lib for each variant.

Une fois ces dossiers en place, vous pouvez référencer tous les fichiers dans votre .nuspec :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>

Microsoft.Data.OData 5.4.0 est un exemple de package qui utilise cette approche.One example package that uses this approach is Microsoft.Data.OData 5.4.0.

Avantages et inconvénients (assemblies de ressources localisées)Advantages and disadvantages (localized resource assemblies)

Le regroupement de toutes les langues dans un package unique présente quelques inconvénients :Bundling all languages in a single package has a few disadvantages:

  1. Métadonnées partagées : étant donné qu’un package NuGet peut uniquement contenir un seul fichier .nuspec, vous pouvez fournir les métadonnées d’une seule langue.Shared metadata: Because a NuGet package can only contain a single .nuspec file, you can provide metadata for only a single language. Autrement dit, NuGet ne prend pas encore en charge les métadonnées localisées.That is, NuGet does not present support localized metadata.
  2. Taille du package : selon le nombre de langues que vous prenez en charge, la bibliothèque peut devenir très volumineuse, ce qui ralentit l’installation et la restauration du package.Package size: Depending on the number of languages you support, the library can become considerably large, which slows installing and restoring the package.
  3. Versions simultanées : le regroupement des fichiers localisés dans un package unique exige la publication simultanée de toutes les ressources dans ce package, au lieu de la publication de chaque localisation séparément.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. De plus, toute mise à jour d’une localisation exige une nouvelle version de la totalité du package.Furthermore, any update to any one localization requires a new version of the entire package.

Toutefois, il a également quelques avantages :However, it also has a few benefits:

  1. Simplicité : les consommateurs du package obtiennent toutes les langues prises en charge dans une installation unique, au lieu de devoir installer chaque langue séparément.Simplicity: Consumers of the package get all supported languages in a single install, rather than having to install each language separately. Un package unique est également plus facile à trouver sur nuget.org.A single package is also easier to find on nuget.org.
  2. Versions couplées : étant donné que tous les assemblys de ressources se trouvent dans le même package que l’assembly principal, ils partagent tous le même numéro de version et ne courent pas le risque d’être découplés par erreur.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.

Packages satellites localisésLocalized satellite packages

Semblable à la manière dont .NET Framework prend en charge les assemblys satellites, cette méthode sépare les ressources localisées et les fichiers XML IntelliSense dans des packages satellites.Similar to how .NET Framework supports satellite assemblies, this method separates localized resources and IntelliSense XML files into satellite packages.

Pour cela, votre package principal utilise la convention de nommage {identifier}.{version}.nupkg et contient l’assembly de la langue par défaut (par exemple, 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). Par exemple, ContosoUtilities.1.0.0.nupkg contiendrait la structure suivante :For example, ContosoUtilities.1.0.0.nupkg would contain the following structure:

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

Un assembly satellite utilise alors la convention de nommage {identifier}.{language}.{version}.nupkg, comme 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. L’identificateur doit correspondre exactement à celui du package principal.The identifier must exactly match that of the primary package.

Comme il s’agit d’un package distinct, il possède son propre fichier .nuspec qui contient des métadonnées localisées.Because this is a separate package, it has its own .nuspec file that contains localized metadata. N’oubliez pas que la langue dans le fichier .nuspec doit correspond à celle utilisée dans le nom de fichier.Be mindful that the language in the .nuspec must match the one used in the filename.

L’assembly satellite doit également déclarer une version exacte du package principal en tant que dépendance, à l’aide de la notation de version [] (consultez Gestion des versions de package).The satellite assembly must also declare an exact version of the primary package as a dependency, using the [] version notation (see Package versioning). Par exemple, ContosoUtilities.de.1.0.0.nupkg doit déclarer une dépendance vis-à-vis de ContosoUtilities.1.0.0.nupkg à l’aide de la notation [1.0.0].For example, ContosoUtilities.de.1.0.0.nupkg must declare a dependency on ContosoUtilities.1.0.0.nupkg using the [1.0.0] notation. Le package satellite peut, bien entendu, avoir un numéro de version différent de celui du package principal.The satellite package can, of course, have a different version number than the primary package.

La structure du package satellite doit alors inclure l’assembly de ressources et le fichier XML IntelliSense dans un sous-dossier qui correspond à {language} dans le nom de fichier du package :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

Remarque : sauf si des sous-cultures spécifiques comme ja-JP sont nécessaires, utilisez toujours l’identificateur de langue le plus général, comme ja.Note: unless specific subcultures such as ja-JP are necessary, always use the higher level language identifier, like ja.

Dans un assembly satellite, NuGet reconnaît uniquement les fichiers inclus dans le dossier qui correspond à {language} dans le nom de fichier.In a satellite assembly, NuGet will recognize only those files in the folder that matches the {language} in the filename. Tous les autres sont ignorés.All others are ignored.

Lorsque toutes ces conventions sont respectées, NuGet reconnaît le package en tant que package satellite et installe les fichiers localisés dans le dossier lib du package principal, comme s’ils avaient été regroupés à l’origine.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. La désinstallation du package satellite permet de supprimer ses fichiers de ce même dossier.Uninstalling the satellite package will remove its files from that same folder.

Vous créez d’autres assemblys satellites de la même façon pour chaque langue prise en charge.You would create additional satellite assemblies in the same way for each supported language. Pour obtenir un exemple, examinez l’ensemble de packages MVC ASP.NET :For an example, examine the set of ASP.NET MVC packages:

Résumé des conventions obligatoiresSummary of required conventions

  • Le package principal doit être nommé {identifier}.{version}.nupkg.Primary package must be named {identifier}.{version}.nupkg
  • Un package satellite doit être nommé {identifier}.{language}.{version}.nupkg.A satellite package must be named {identifier}.{language}.{version}.nupkg
  • Le fichier .nuspec d’un package satellite doit spécifier sa langue pour correspondre au nom de fichier.A satellite package's .nuspec must specify its language to match the filename.
  • Un package satellite doit déclarer une dépendance vis-à-vis d’une version exacte du package principal à l’aide de la notation [] dans son fichier .nuspec.A satellite package must declare a dependency on an exact version of the primary using the [] notation in its .nuspec file. Les plages ne sont pas prises en charge.Ranges are not supported.
  • Un package satellite doit placer des fichiers dans le dossier lib\[{framework}\]{language} qui correspondent exactement à {language} dans le nom de fichier.A satellite package must place files in the lib\[{framework}\]{language} folder that exactly matches {language} in the filename.

Avantages et inconvénients (packages satellites)Advantages and disadvantages (satellite packages)

L’utilisation de packages satellites présente quelques avantages :Using satellite packages has a few benefits:

  1. Taille du package : l’encombrement global du package principal est réduit et les consommateurs payent uniquement les coûts de chaque langue qu’ils souhaitent utiliser.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. Métadonnées distinctes : chaque package satellite possède son propre fichier .nuspec et, par conséquent, ses propres métadonnées localisées.Separate metadata: Each satellite package has its own .nuspec file and thus its own localized metadata because. Cela peut permettre à certains consommateurs de trouver plus facilement des packages sur nuget.org en utilisant des termes localisés.This can allow some consumers to find packages more easily by searching nuget.org with localized terms.
  3. Versions découplées : il est possible de publier les assemblys satellites progressivement, plutôt que tous en même temps, ce qui vous permet d’étaler vos efforts de localisation.Decoupled releases: Satellite assemblies can be released over time, rather than all at once, allowing you to spread out your localization efforts.

Néanmois, les packages satellites présentent aussi quelques inconvénients :However, satellite packages have their own set of disadvantages:

  1. Multiplicité : au lieu d’un package unique, vous avez de nombreux packages pouvant engendrer des résultats de recherche confus sur nuget.org et une longue liste de références dans un projet Visual Studio.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. Conventions strictes.Strict conventions. Les packages satellites doivent suivre les conventions à la lettre sans quoi les versions localisées ne sont pas correctement sélectionnées.Satellite packages must follow the conventions exactly or the localized versions won't be picked up properly.
  3. Gestion de versions : chaque package satellite doit avoir une dépendance de version exacte vis-à-vis du package principal.Versioning: Each satellite package must have an exact version dependency on the primary package. Cela signifie que la mise à jour du package principal peut nécessiter celle de tous les packages satellites également, même si les ressources n’ont pas changé.This means that updating the primary package may require updating all satellite packages as well, even if the resources didn't change.