Partilhar via

Criando pacotes NuGet localizados

Há duas maneiras de criar versões localizadas de uma biblioteca:

  1. Inclua todos os assemblies de recursos localizados em um único pacote.
  2. Crie pacotes de satélite localizados separados seguindo um conjunto rigoroso de convenções.

Ambos os métodos têm suas vantagens e desvantagens, conforme descrito nas seções a seguir.

Assemblies de recursos localizados em um único pacote

Incluir assemblies de recursos localizados em um único pacote é normalmente a abordagem mais simples. Para fazer isso, crie pastas dentro lib para o idioma suportado diferente do padrão do pacote (presumido como en-us). Nessas pastas, você pode colocar assemblies de recursos e arquivos XML do IntelliSense localizados.

Por exemplo, a seguinte estrutura de pastas suporta, alemão (de), italiano (it), japonês (ja), russo (ru), chinês (simplificado) (zh-Hans) e chinês (tradicional) (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

Você pode ver que os idiomas estão todos listados dentro da pasta da estrutura de framework alvo net40. Se você estiver suportando várias estruturas, então você tem uma pasta em lib para cada variante.

Com essas pastas no lugar, você então referencia todos os arquivos em seu .nuspec:

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

Um pacote de exemplo que usa essa abordagem é Microsoft.Data.OData 5.4.0.

Vantagens e desvantagens (assemblies de recursos localizados)

A agregação de todas as línguas num único pacote apresenta algumas desvantagens:

  1. Metadados compartilhados: como um pacote NuGet só pode conter um único .nuspec arquivo, você pode fornecer metadados para apenas um único idioma. Ou seja, o NuGet não apresenta suporte a metadados localizados.
  2. Tamanho do pacote: Dependendo do número de idiomas suportados, a biblioteca pode se tornar consideravelmente grande, o que atrasa a instalação e a restauração do pacote.
  3. Lançamentos simultâneos: agregar arquivos localizados em um único pacote requer que você libere todos os ativos desse pacote simultaneamente, em vez de poder liberar cada localização separadamente. Além disso, qualquer atualização para qualquer localização requer uma nova versão do pacote inteiro.

No entanto, também tem alguns benefícios:

  1. Simplicidade: Os consumidores do pacote obtêm todos os idiomas suportados em uma única instalação, em vez de ter que instalar cada idioma separadamente. Um único pacote também é mais fácil de encontrar no nuget.org.
  2. Versões acopladas: Como todos os assemblies de recursos estão no mesmo pacote que o assembly principal, todos eles compartilham o mesmo número de versão e não correm o risco de serem erroneamente dissociados.

Pacotes de satélite localizados

Semelhante a como o .NET Framework suporta assemblies satélite, esse método separa recursos localizados e arquivos XML IntelliSense em pacotes satélite.

Para isso, o seu pacote principal utiliza a convenção de nomenclatura {identifier}.{version}.nupkg e contém a assembly para a língua padrão (como, por exemplo, 'en-US'). Por exemplo, ContosoUtilities.1.0.0.nupkg conteria a seguinte estrutura:

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

Em seguida, um sistema de satélites usa a convenção de nomenclatura {identifier}.{language}.{version}.nupkg, como ContosoUtilities.de.1.0.0.nupkg. O identificador deve corresponder exatamente ao do pacote primário.

Como este é um pacote separado, ele tem seu próprio .nuspec arquivo que contém metadados localizados. Esteja ciente de que o idioma no .nuspecdeve corresponder ao usado no nome do arquivo.

O assembly satélite também deve declarar uma versão exata do pacote primário como uma dependência, usando a notação de versão [] (consulte Controle de versão do pacote). Por exemplo, ContosoUtilities.de.1.0.0.nupkg deve declarar uma dependência no ContosoUtilities.1.0.0.nupkg usando a notação [1.0.0]. O pacote satélite pode, é claro, ter um número de versão diferente do pacote principal.

A estrutura do pacote satélite deve então incluir o assembly de recursos e o ficheiro XML IntelliSense numa subpasta que corresponda a '{language}' no nome do ficheiro do pacote.

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

Nota: exceto quando subculturas específicas ja-JP são necessárias, utilize sempre o identificador de idioma de nível superior, como ja.

Em um assembly satélite, o NuGet reconhecerá apenas os arquivos na pasta que correspondem a {language} no nome do arquivo. Todos os outros são ignorados.

Quando todas essas convenções forem atendidas, o NuGet reconhecerá o pacote como um pacote satélite e instalará os arquivos localizados na pasta do lib pacote primário, como se tivessem sido originalmente empacotados. A desinstalação do pacote satélite removerá seus arquivos dessa mesma pasta.

Você criaria assemblies satélite adicionais da mesma maneira para cada idioma suportado. Para obter um exemplo, examine o conjunto de ASP.NET pacotes MVC:

Resumo das convenções exigidas

  • O pacote primário deve ser nomeado {identifier}.{version}.nupkg
  • Um pacote de satélite deve ser nomeado {identifier}.{language}.{version}.nupkg
  • Um pacote satélite .nuspec deve especificar seu idioma para corresponder ao nome do arquivo.
  • Um pacote satélite deve declarar uma dependência de uma versão exata do primário usando a notação [] no arquivo .nuspec. Não há suporte para intervalos.
  • Um pacote de satélite deve colocar arquivos lib\[{framework}\]{language} na pasta que corresponde exatamente {language} ao nome do arquivo.

Vantagens e desvantagens (pacotes satélite)

Usar pacotes de satélite tem alguns benefícios:

  1. Tamanho do pacote: a pegada geral do pacote principal é minimizada e os consumidores incorrem apenas nos custos de cada idioma que desejam usar.
  2. Metadados separados: Cada pacote de satélite tem seu próprio .nuspec arquivo e, portanto, seus próprios metadados localizados. Isso pode permitir que alguns consumidores encontrem pacotes mais facilmente, pesquisando nuget.org com termos localizados.
  3. Lançamentos dissociados: os conjuntos de satélites podem ser liberados ao longo do tempo, em vez de todos de uma só vez, permitindo que você espalhe seus esforços de localização.

No entanto, os pacotes de satélite têm o seu próprio conjunto de desvantagens:

  1. Clutter: Em vez de um único pacote, você tem muitos pacotes que podem levar a resultados de pesquisa desorganizados no nuget.org e uma lista extensa de referências em um projeto do Visual Studio.
  2. Convenções rigorosas. Os pacotes de satélite devem seguir exatamente as convenções ou as versões localizadas não serão captadas corretamente.
  3. Controle de versão: Cada pacote satélite deve ter uma dependência de versão exata do pacote primário. Isso significa que a atualização do pacote principal pode exigir a atualização de todos os pacotes de satélite também, mesmo que os recursos não tenham sido alterados.
  • Last updated on