Condividi tramite

Creazione di pacchetti NuGet localizzati

Esistono due modi per creare versioni localizzate di una libreria:

  1. Includere tutti gli assembly di risorse localizzati in un singolo pacchetto.
  2. Creare pacchetti satellite localizzati separati seguendo un set rigoroso di convenzioni.

Entrambi i metodi presentano vantaggi e svantaggi, come descritto nelle sezioni seguenti.

Assembly di risorse localizzati in un singolo pacchetto

L'inclusione di assembly di risorse localizzati in un singolo pacchetto è in genere l'approccio più semplice. A tale scopo, creare cartelle all'interno lib della lingua supportata diversa da quella predefinita del pacchetto (si presuppone che sia en-us). In queste cartelle è possibile inserire assembly di risorse e file XML IntelliSense localizzati.

Ad esempio, la struttura di cartelle seguente supporta, tedesco (de), italiano (it), giapponese (ja), russo (ru), cinese (semplificato) (zh-Hans) e cinese (tradizionale) (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

È possibile notare che i linguaggi sono elencati tutti sotto la cartella del net40 framework di destinazione. Se si supportano più framework, è disponibile una cartella in lib per ogni variante.

Con queste cartelle sul posto, si fa quindi riferimento a tutti i file in .nuspec:

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

Un pacchetto di esempio che usa questo approccio è Microsoft.Data.OData 5.4.0.

Vantaggi e svantaggi (assembly di risorse localizzate)

L'aggregazione di tutte le lingue in un singolo pacchetto presenta alcuni svantaggi:

  1. Metadati condivisi: poiché un pacchetto NuGet può contenere solo un singolo .nuspec file, è possibile fornire metadati solo per una singola lingua. Ovvero, NuGet non supporta i metadati localizzati.
  2. Dimensioni del pacchetto: a seconda del numero di lingue supportate, la libreria può diventare notevolmente grande, rallentando l'installazione e il ripristino del pacchetto.
  3. Versioni simultanee: la creazione di bundle di file localizzati in un singolo pacchetto richiede il rilascio simultaneo di tutti gli asset in tale pacchetto, invece di poter rilasciare ogni localizzazione separatamente. Inoltre, qualsiasi aggiornamento a qualsiasi localizzazione richiede una nuova versione dell'intero pacchetto.

Tuttavia, offre anche alcuni vantaggi:

  1. Semplicità: i consumer del pacchetto ottengono tutte le lingue supportate in un'unica installazione, invece di dover installare ogni lingua separatamente. Un singolo pacchetto è anche più semplice da trovare in nuget.org.
  2. Versioni associate: poiché tutti gli assembly di risorse si trovano nello stesso pacchetto dell'assembly primario, condividono tutti lo stesso numero di versione e non rischiano di essere erroneamente disaccoppiati.

Pacchetti satellite localizzati

Analogamente al modo in cui .NET Framework supporta gli assembly satellite, questo metodo separa le risorse localizzate e i file XML in IntelliSense in pacchetti satellite.

A tale scopo, il pacchetto primario usa la convenzione {identifier}.{version}.nupkg di denominazione e contiene l'assembly per la lingua predefinita, ad esempio en-US. Ad esempio, ContosoUtilities.1.0.0.nupkg conterrà la struttura seguente:

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

Un assembly satellite quindi utilizza la convenzione di denominazione {identifier}.{language}.{version}.nupkg, come ContosoUtilities.de.1.0.0.nupkg. L'identificatore deve corrispondere esattamente a quello del pacchetto primario.

Poiché si tratta di un pacchetto separato, ha un proprio .nuspec file che contiene metadati localizzati. Tenere presente che la lingua in .nuspecdeve corrispondere a quella usata nel nome file.

L'assembly satellite deve anche dichiarare l'esatta versione del pacchetto primario come una dipendenza, usando la notazione di versione [] (vedere Versionamento del pacchetto). Ad esempio, ContosoUtilities.de.1.0.0.nupkg deve dichiarare una dipendenza da ContosoUtilities.1.0.0.nupkg usando la notazione [1.0.0]. Il pacchetto satellite può, naturalmente, avere un numero di versione diverso rispetto al pacchetto primario.

La struttura del pacchetto satellite deve quindi includere l'assembly di risorse e il file Xml IntelliSense in una sottocartella corrispondente {language} al nome file del pacchetto:

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

Nota: a meno che sottoculture specifiche siano necessarie, si usi sempre l'identificatore di lingua di livello superiore, come ja.

In un assembly satellite NuGet riconoscerà solo i file nella cartella che corrispondono a {language} nel nome file. Tutti gli altri vengono ignorati.

Quando vengono soddisfatte tutte queste convenzioni, NuGet riconoscerà il pacchetto come pacchetto satellite e installerà i file localizzati nella cartella del lib pacchetto primario, come se fossero stati originariamente raggruppati. La disinstallazione del pacchetto satellite rimuoverà i file dalla stessa cartella.

È possibile creare assembly satellite aggiuntivi nello stesso modo per ogni linguaggio supportato. Per un esempio, esaminare il set di pacchetti MVC ASP.NET:

Riepilogo delle convenzioni richieste

  • Il pacchetto primario deve essere denominato {identifier}.{version}.nupkg
  • Un pacchetto satellite deve essere denominato {identifier}.{language}.{version}.nupkg
  • Un pacchetto .nuspec satellite deve specificare la lingua in modo che corrisponda al nome file.
  • Un pacchetto satellite deve dichiarare una dipendenza da una versione esatta del primario usando la notazione [] nel relativo .nuspec file. Gli intervalli non sono supportati.
  • Un pacchetto satellite deve inserire i file nella lib\[{framework}\]{language} cartella che corrisponde esattamente al {language} nome file.

Vantaggi e svantaggi (pacchetti satellite)

L'uso di pacchetti satellite offre alcuni vantaggi:

  1. Dimensioni del pacchetto: il footprint complessivo del pacchetto principale è ridotto al minimo e i consumatori sostengono solo i costi di ogni lingua che desiderano utilizzare.
  2. Metadati separati: ogni pacchetto satellite ha un proprio .nuspec file e quindi i propri metadati localizzati. Ciò consente ad alcuni consumer di trovare più facilmente i pacchetti cercando nuget.org con termini localizzati.
  3. Versioni disaccoppiate: gli assembly satellite possono essere rilasciati nel tempo, anziché tutti contemporaneamente, consentendo di distribuire le attività di localizzazione.

Tuttavia, i pacchetti satellite hanno un proprio set di svantaggi:

  1. Confusione: invece di un singolo pacchetto, hai molti pacchetti che possono causare risultati di ricerca disordinati su nuget.org e un lungo elenco di riferimenti in un progetto di Visual Studio.
  2. Convenzioni rigorose. I pacchetti satellite devono seguire esattamente le convenzioni o le versioni localizzate non verranno prelevate correttamente.
  3. Controllo delle versioni: ogni pacchetto satellite deve avere una dipendenza esatta della versione dal pacchetto primario. Ciò significa che l'aggiornamento del pacchetto primario potrebbe richiedere anche l'aggiornamento di tutti i pacchetti satellite, anche se le risorse non sono cambiate.
  • Last updated on