Поделиться через

Создание локализованных пакетов NuGet

Существует два способа создания локализованных версий библиотеки:

  1. Включите все локализованные сборки ресурсов в один пакет.
  2. Создайте отдельные локализованные спутниковые пакеты, следуя строгому набору соглашений.

Оба метода имеют свои преимущества и недостатки, как описано в следующих разделах.

Локализованные сборки ресурсов в одном пакете

Включение локализованных сборок ресурсов в один пакет обычно является самым простым подходом. Для этого создайте папки в lib поддерживаемом языке, отличном от используемого по умолчанию пакета (предполагается, что en-us). В этих папках можно разместить сборки ресурсов и локализованные XML-файлы IntelliSense.

Например, следующая структура папок поддерживает немецкий (de), итальянский (it), японский (ja), русский (ru), китайский (упрощённый) (zh-Hans), и китайский (традиционный) (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

Вы можете увидеть, что языки перечислены под папкой целевой net40 платформы. Если вы поддерживаете несколько платформ, у вас есть папка lib для каждого варианта.

Далее, настроив эти папки, вы сможете ссылаться на все файлы в .nuspec.

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

Одним из примеров пакета, использующего этот подход, является Microsoft.Data.OData 5.4.0.

Преимущества и недостатки (локализованные ассамблеи ресурсов)

Объединение всех языков в одном пакете имеет несколько недостатков:

  1. Общие метаданные. Так как пакет NuGet может содержать только один файл, можно предоставить метаданные только для одного .nuspec языка. То есть NuGet не поддерживает локализованные метаданные.
  2. Размер пакета. В зависимости от количества поддерживаемых языков библиотека может стать значительно большой, что замедляет установку и восстановление пакета.
  3. Одновременные выпуски: локализация локализованных файлов в один пакет требует одновременного выпуска всех ресурсов в этом пакете, а не возможность выпуска каждой локализации отдельно. Кроме того, для любого обновления для любой локализации требуется новая версия всего пакета.

Тем не менее, он также имеет несколько преимуществ:

  1. Простота. Потребители пакета получают все поддерживаемые языки в одной установке, а не устанавливать каждый язык отдельно. Один пакет также проще найти на nuget.org.
  2. Связанные версии: так как все сборки ресурсов находятся в одном пакете вместе с основной сборкой, они все имеют одинаковый номер версии и не рискуют быть ошибочно отделёнными.

Локализованные спутниковые пакеты

Аналогично тому, как .NET Framework поддерживает вспомогательные сборки, этот метод разделяет локализованные ресурсы и XML-файлы IntelliSense на вспомогательные пакеты.

Для этого основной пакет использует соглашение {identifier}.{version}.nupkg об именовании и содержит сборку для языка по умолчанию (например, en-US). Например, ContosoUtilities.1.0.0.nupkg будет содержать следующую структуру:

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

Затем в спутниковой сборке используется соглашение об именовании {identifier}.{language}.{version}.nupkg, например ContosoUtilities.de.1.0.0.nupkg. Идентификатор должен точно соответствовать идентификатору основного пакета.

Так как это отдельный пакет, он имеет собственный .nuspec файл, содержащий локализованные метаданные. Помните, что язык в .nuspec поле должен соответствовать языку, используемому в имени файла.

Вспомогательные сборки также должны объявлять точную версию основного пакета как зависимость, используя нотацию версий [] (см. раздел "Управление версиями пакетов"). Например, ContosoUtilities.de.1.0.0.nupkg должен объявить зависимость от ContosoUtilities.1.0.0.nupkg, используя нотацию [1.0.0]. Вспомогательный пакет, конечно, может иметь другой номер версии, чем основной пакет.

Затем структура спутникового пакета должна включать сборку ресурсов и XML-файл IntelliSense в вложенную папку, которая соответствует названию файла пакета {language}.

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

Примечание. Если не требуется определенная субкультура ja-JP , всегда используйте идентификатор языка более высокого уровня, например ja.

В спутниковой сборке NuGet распознает только те файлы в папке, которая совпадает с {language} в имени файла. Все остальные игнорируются.

Когда выполняются все эти соглашения, NuGet распознает пакет как вспомогательный пакет и установит локализованные файлы в папку основного пакета lib , как если бы они были первоначально упакованы. Удаление вспомогательного пакета приведет к удалению файлов из той же папки.

Вы создадите дополнительные сателлитные сборки таким же образом для каждого поддерживаемого языка. Например, изучите набор пакетов MVC ASP.NET:

Сводка обязательных соглашений

  • Основной пакет должен быть назван {identifier}.{version}.nupkg
  • Спутниковый пакет должен быть назван {identifier}.{language}.{version}.nupkg
  • Спутниковый пакет .nuspec должен указать свой язык, чтобы он соответствовал имени файла.
  • Вспомогательный пакет должен объявить зависимость от точной версии основного пакета, используя нотацию [] в файле .nuspec. Диапазоны не поддерживаются.
  • Спутниковый пакет должен поместить файлы в папку lib\[{framework}\]{language}, которая точно соответствует {language} в имени файла.

Преимущества и недостатки (спутниковые пакеты)

Использование спутниковых пакетов имеет несколько преимуществ:

  1. Размер пакета: общий объем основного пакета сведен к минимуму, и потребители несут только затраты на каждый язык, который они хотят использовать.
  2. Отдельные метаданные: каждый сателлитный пакет имеет собственный .nuspec файл и, таким образом, собственные локализованные метаданные. Это позволяет некоторым потребителям проще находить пакеты, выполняя поиск nuget.org с локализованными терминами.
  3. Отсоединяемые выпуски: сателлитные сборки можно выпускать постепенно, а не все сразу, позволяя распределить усилия по локализации.

Однако спутниковые пакеты имеют собственный набор недостатков:

  1. Загромождения. Вместо одного пакета у вас есть множество пакетов, которые могут привести к загромождениям результатов поиска по nuget.org и длинному списку ссылок в проекте Visual Studio.
  2. Строгие соглашения. Спутниковые пакеты должны точно соответствовать соглашениям, иначе локализованные версии не будут правильно обработаны.
  3. Управление версиями. Каждый вспомогательный пакет должен иметь точную зависимость версии от основного пакета. Это означает, что обновление основного пакета может потребовать обновления всех вспомогательных пакетов, даже если ресурсы не изменились.
  • Last updated on