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

Статья
08/10/2023

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

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

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

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

Включение локализованных сборок ресурсов в один пакет обычно является самым простым подходом. Для этого создайте внутри 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.

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

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

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

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

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

Локализованные вспомогательные пакеты

По аналогии с тем, как .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:

Microsoft.AspNet.Mvc (основной английский язык)
Microsoft.AspNet.Mvc.de (немецкий)
Microsoft.AspNet.Mvc.ja (японский)
Microsoft.AspNet.Mvc.zh Hans (китайский (упрощенное письмо))
Microsoft.AspNet.Mvc.zh Hant (китайский (традиционное письмо))

Сводка по необходимым соглашениям

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

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

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

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

Однако вспомогательные пакеты имеют и определенные недостатки:

Беспорядок: вместо одного пакета вы получаете несколько, что может привести к загромождению результатов поиска на сайте nuget.org и длинному списку ссылок в проекте Visual Studio.
Строгие соглашения. Вспомогательные пакеты должны точно соответствовать соглашениям, в противном случае локализованные версии не будут приняты должным образом.
Управление версиями: каждый вспомогательный пакет должен иметь зависимость по точной версии от основного пакета. Это означает, что при обновлении основного пакета может потребоваться обновление всех вспомогательных пакетов, даже если ресурсы не изменились.

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