Delen via

Gelokaliseerde NuGet-pakketten maken

Er zijn twee manieren om gelokaliseerde versies van een bibliotheek te maken:

  1. Alle gelokaliseerde resources-assemblies opnemen in één pakket.
  2. Maak afzonderlijke gelokaliseerde satellietpakketten door een strikte set conventies te volgen.

Beide methoden hebben hun voor- en nadelen, zoals beschreven in de volgende secties.

Gelokaliseerde resource-assemblages in één pakket

Het opnemen van gelokaliseerde resourceassembly's in één pakket is doorgaans de eenvoudigste benadering. Hiervoor maakt u mappen in lib voor ondersteunde talen, anders dan de pakketstandaard (zoals bijvoorbeeld en-us). In deze mappen kunt u resourceassembly's en gelokaliseerde IntelliSense XML-bestanden plaatsen.

De volgende mapstructuur ondersteunt bijvoorbeeld Duits (de), Italiaans (it), Japans (ja), Russisch (ru), Chinees (vereenvoudigd) (zh-Hans) en Chinees (traditioneel) (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

U kunt zien dat de talen allemaal vermeld staan onder de net40 doelframeworkmap. Als u meerdere frameworks ondersteunt, hebt u voor elke variant een aparte map onder lib.

Als deze mappen aanwezig zijn, verwijst u vervolgens naar alle bestanden in uw .nuspec:

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

Een voorbeeldpakket dat gebruikmaakt van deze benadering is Microsoft.Data.OData 5.4.0.

Voor- en nadelen (gelokaliseerde resourceverzamelingen)

Het bundelen van alle talen in één pakket heeft een aantal nadelen:

  1. Gedeelde metagegevens: omdat een NuGet-pakket slechts één .nuspec bestand kan bevatten, kunt u metagegevens opgeven voor slechts één taal. Dat wil gezegd, NuGet biedt geen ondersteuning voor gelokaliseerde metagegevens.
  2. Pakketgrootte: afhankelijk van het aantal talen dat u ondersteunt, kan de bibliotheek aanzienlijk groot worden, wat de installatie en het herstellen van het pakket vertraagt.
  3. Gelijktijdige releases: het bundelen van gelokaliseerde bestanden in één pakket vereist dat u alle assets in dat pakket tegelijk vrijgeeft, in plaats van dat u elke lokalisatie afzonderlijk kunt vrijgeven. Bovendien is voor elke update naar elke lokalisatie een nieuwe versie van het hele pakket vereist.

Het heeft echter ook enkele voordelen:

  1. Eenvoud: consumenten van het pakket krijgen alle ondersteunde talen in één installatie, in plaats van elke taal afzonderlijk te installeren. Een enkel pakket is ook gemakkelijker te vinden op nuget.org.
  2. Gekoppelde versies: omdat alle resourceassembly's zich in hetzelfde pakket bevinden als de primaire assembly, delen ze allemaal hetzelfde versienummer en lopen ze geen risico dat ze per ongeluk worden losgekoppeld.

Gelokaliseerde satellietpakketten

Net zoals .NET Framework satelliet-assembly's ondersteunt, verplaatst deze methode gelokaliseerde middelen en IntelliSense XML-bestanden naar satellietpakketten.

Hiervoor gebruikt uw primaire pakket de naamconventie {identifier}.{version}.nupkg en bevat de assembly voor de standaardtaal (zoals en-US). Bevat bijvoorbeeld ContosoUtilities.1.0.0.nupkg de volgende structuur:

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

Een satellietassembly gebruikt vervolgens de naamgevingsconventie {identifier}.{language}.{version}.nupkg, zoals ContosoUtilities.de.1.0.0.nupkg. De id moet exact overeenkomen met die van het primaire pakket.

Omdat dit een afzonderlijk pakket is, heeft het een eigen .nuspec bestand dat gelokaliseerde metagegevens bevat. Houd er rekening mee dat de taal in .nuspec overeen moet komen met de taal die in de bestandsnaam wordt gebruikt.

De satellietassembly moet ook een exacte versie van het primaire pakket declareren als een afhankelijkheid, met behulp van de [] versie-notatie (zie Pakketversiebeheer). Bijvoorbeeld, ContosoUtilities.de.1.0.0.nupkg moet een afhankelijkheid op ContosoUtilities.1.0.0.nupkg verklaren met behulp van de [1.0.0] notatie. Het satellietpakket kan natuurlijk een ander versienummer hebben dan het primaire pakket.

De structuur van het satellietpakket moet vervolgens de resourceassembly en het XML IntelliSense-bestand bevatten in een submap die overeenkomt {language} met de bestandsnaam van het pakket:

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

Opmerking: tenzij specifieke subculturen nodig zijn ja-JP, moet u altijd de taalaanduiding op een hoger niveau gebruiken, zoals ja.

In een satellietassembly herkent NuGet alleen die bestanden in de map die overeenkomt met de {language} bestandsnaam. Alle anderen worden genegeerd.

Wanneer aan al deze conventies wordt voldaan, herkent NuGet het pakket als satellietpakket en installeert u de gelokaliseerde bestanden in de map van lib het primaire pakket, alsof ze oorspronkelijk waren gebundeld. Als u het satellietpakket verwijdert, worden de bestanden uit dezelfde map verwijderd.

U maakt extra satellietassembly's op dezelfde manier voor elke ondersteunde taal. Bekijk bijvoorbeeld de set ASP.NET MVC-pakketten:

Samenvatting van de vereiste conventies

  • Primair pakket moet de naam hebben {identifier}.{version}.nupkg
  • Een satellietpakket moet de naam hebben {identifier}.{language}.{version}.nupkg
  • Een satellietpakket .nuspec moet de taal opgeven die overeenkomt met de bestandsnaam.
  • Een satellietpakket moet een afhankelijkheid declareren van een exacte versie van de primaire versie met behulp van de [] notatie in het .nuspec bestand. Bereiken worden niet ondersteund.
  • Een satellietpakket moet bestanden in de lib\[{framework}\]{language} map plaatsen die exact overeenkomen {language} met de bestandsnaam.

Voor- en nadelen (satellietpakketten)

Het gebruik van satellietpakketten heeft enkele voordelen:

  1. Pakketgrootte: de totale footprint van het primaire pakket wordt geminimaliseerd en consumenten betalen alleen de kosten van elke taal die ze willen gebruiken.
  2. Afzonderlijke metagegevens: elk satellietpakket heeft een eigen .nuspec bestand en dus zijn eigen gelokaliseerde metagegevens. Hierdoor kunnen sommige consumenten gemakkelijker pakketten vinden door te zoeken nuget.org met gelokaliseerde termen.
  3. Losgekoppelde releases: Satellietassembly's kunnen in de loop van de tijd worden vrijgegeven in plaats van allemaal tegelijk, zodat u uw lokalisatie-inspanningen kunt verspreiden.

Satellietpakketten hebben echter hun eigen set nadelen:

  1. Rommel: In plaats van één pakket hebt u veel pakketten die kunnen leiden tot rommelige zoekresultaten op nuget.org en een lange lijst met verwijzingen in een Visual Studio-project.
  2. Strikte conventies. Satellietpakketten moeten de conventies exact volgen of de gelokaliseerde versies worden niet goed opgehaald.
  3. Versiebeheer: elk satellietpakket moet een exacte versieafhankelijkheid hebben van het primaire pakket. Dit betekent dat het bijwerken van het primaire pakket mogelijk ook het bijwerken van alle satellietpakketten vereist, zelfs als de resources niet zijn gewijzigd.
  • Last updated on