Создание локализованных пакетов 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. Управление версиями: каждый вспомогательный пакет должен иметь зависимость по точной версии от основного пакета. Это означает, что при обновлении основного пакета может потребоваться обновление всех вспомогательных пакетов, даже если ресурсы не изменились.