Предоставление локализованных ресурсов для языков и региональных параметров в приложении ASP.NET Core
Примечание.
Это не последняя версия этой статьи. В текущем выпуске см . версию .NET 9 этой статьи.
Предупреждение
Эта версия ASP.NET Core больше не поддерживается. Дополнительные сведения см. в политике поддержки .NET и .NET Core. В текущем выпуске см . версию .NET 9 этой статьи.
Внимание
Эта информация относится к предварительному выпуску продукта, который может быть существенно изменен до его коммерческого выпуска. Майкрософт не предоставляет никаких гарантий, явных или подразумеваемых, относительно приведенных здесь сведений.
В текущем выпуске см . версию .NET 9 этой статьи.
Авторы: Рик Андерсон (Rick Anderson), Дэмиен Боуден (Damien Bowden), Барт Каликсто (Bart Calixto), Надим Афана (Nadeem Afana) и Хишам Бин Атея (Hisham Bin Ateya)
Одной из задач локализации приложения является предоставление локализованных строк в файлах ресурсов. В этой статье описывается работа с файлами ресурсов.
SupportedCultures и SupportedUICultures.
ASP.NET Core содержит две коллекции значений языка и региональных параметров, SupportedCultures а также SupportedUICultures. Объект CultureInfo для SupportedCultures определения результатов функций, зависимых от языка и региональных параметров, таких как дата, время, число и форматирование валют. SupportedCultures также определяет порядок сортировки текста, соглашения о регистре символов и способы сравнения строк. Дополнительные StringComparer.CurrentCulture сведения о том, как сервер получает язык и региональные параметры. Значение SupportedUICultures определяет то, какие строки переводов (в файлах RESX) ищет объект ResourceManager. Просто ResourceManager ищет строки, зависящие от языка и региональных параметров, которые определяются CurrentUICulture. Каждый поток в .NET имеет объекты CurrentCulture и CurrentUICulture. ASP.NET Core проверяет эти значения при обработке функций, зависящих от языка и региональных параметров. Например, если для текущего потока заданы язык и региональные параметры "en-US" (английский, США), метод DateTime.Now.ToLongDateString() выводит строку "Thursday, February 18, 2016", но если CurrentCulture имеет значение "ru-RU" (русский, Россия), выводится строка "четверг, 18 февраля 2016 г."
Файлы ресурсов
ПРИМЕЧАНИЕ. Средство просмотра и редактор resX предоставляет альтернативный механизм для работы с файлами ресурсов с помощью Visual Studio Code.
Файл ресурсов — это полезное средство для отделения локализуемых строк от кода. Переведенные строки на языках, отличных от языка по умолчанию, содержатся в отдельных файлах ресурсов с расширением RESX. Например, может потребоваться создать испанский файл ресурсов с именем Welcome.es.resx , содержащий переведенные строки. "es" — это код испанского языка. Чтобы создать этот файл ресурсов в Visual Studio, выполните указанные ниже действия.
В Обозреватель решений щелкните правой кнопкой мыши папку, содержащую файл ресурса, а затем нажмите кнопку "Добавить>новый элемент".
В поле Поиск установленных шаблонов введите слово "ресурс" и укажите имя файла.
Введите значение ключа (строку на исходном языке) в столбце Имя и переведенную строку в столбце Значение.
В Visual Studio отобразится файл Welcome.es.resx.
Именование файлов ресурсов
Имена ресурсов представляют собой полные имена типов соответствующего класса за исключением имени сборки. Например, ресурс на французском языке в проекте, главная сборка которого имеет имя LocalizationWebsite.Web.dll, для класса LocalizationWebsite.Web.Startup будет иметь имя Startup.fr.resx. Ресурс для класса LocalizationWebsite.Web.Controllers.HomeController будет иметь имя Controllers.HomeController.fr.resx. Если пространство имен целевого класса не совпадает с именем сборки, необходимо использовать полное имя типа. Например, в образце проекта ресурс для типа ExtraNamespace.Tools будет иметь имя ExtraNamespace.Tools.fr.resx.
В примере проекта ConfigureServices метод задает ResourcesPath значение Resources, поэтому относительный путь проекта для home французского файла ресурсов контроллера — Resources/Controllers.HomeController.fr.resx. Кроме того, для упорядочения файлов ресурсов можно использовать папки. Для контроллера home путь будет иметь значение Resources/Controllers/HomeController.fr.resx. Если параметр ResourcesPath не используется, файл RESX будет находиться в базовом каталоге проекта. Файл ресурса для HomeController будет иметь имя Controllers.HomeController.fr.resx. Выбор соглашения об именовании на основе точечной нотации или пути зависит от того, как следует упорядочивать файлы ресурсов.
| Имя ресурса | Точечная нотация или путь |
|---|---|
| Resources/Controllers.HomeController.fr.resx | Точки |
| Resources/Controllers/HomeController.fr.resx | Путь |
Файлы ресурсов, для которых используется директива @inject IViewLocalizer в представлениях Razor, следуют той же модели. Файлу ресурсов для представления может присваиваться имя на основе либо точечной нотации, либо пути. В файле ресурсов для представления Razor имитируется путь к связанному файлу представления. Если для ResourcesPath задано значение Resources, то файл ресурсов на французском языке, связанный с представлением Views/Home/About.cshtml, может иметь одно из следующих имен.
Resources/Views/Home/About.fr.resx
Resources/Views.Home.About.fr.resx
Если параметр ResourcesPath не используется, файл RESX для представления будет находиться в той же папке, что и представление.
RootNamespaceAttribute
Атрибут RootNamespaceAttribute предоставляет корневое пространство имен сборки, если корневое пространство имен сборки отличается от имени сборки.
Предупреждение
Это может произойти, если имя проекта — недопустимый идентификатор .NET. Например, my-project-name.csproj будет использовать корневое пространство имен my_project_name и имя сборки my-project-name, что повлечет эту ошибку.
Если корневое пространство имен сборки отличается от имени сборки
- Локализация не работает по умолчанию.
- Локализация завершается сбоем из-за метода поиска ресурсов в сборке.
RootNamespace— это значение во время сборки, которое недоступно выполняющемуся процессу.
Если RootNamespace отличается от AssemblyName, включите следующее в файл AssemblyInfo.cs (со значениями параметров, замененными фактическими значениями).
using System.Reflection;
using Microsoft.Extensions.Localization;
[assembly: ResourceLocation("Resource Folder Name")]
[assembly: RootNamespace("App Root Namespace")]
Приведенный выше код обеспечивает успешное разрешение RESX-файлов.
Резервный язык и региональные параметры
При поиске ресурса локализации использует резервный язык и региональные параметры. Если запрошенный язык и региональные параметры не найдены, используется родительский язык и региональные параметры. В стороне CultureInfo.Parent свойство представляет родительский язык и региональные параметры. Это обычно (но не всегда) означает удаление национального знака из кода языка и культуры. Например, диалект испанского в Мексике — es-MX. Родительский элемент "es" (испанский) не относится к той или иной стране.
Допустим, сайт получает запрос на ресурс "Приветствие" с использованием языка и региональных параметров fr-CA. Система локализации ищет в следующих ресурсах по порядку и выбирает первое совпадение:
- Welcome.fr-CA.resx
- Welcome.fr.resx
- Welcome.resx (если
NeutralResourcesLanguage— fr-CA)
Если вы удалите указатель языка и региональных параметров ".fr" и при этом задан французский язык и региональные параметры, будет считан файл ресурсов по умолчанию и строки локализуются. Диспетчер ресурсов назначает ресурс по умолчанию или резервный ресурс на тот случай, когда соответствия запрошенному языку и региональным параметрам не найдено. Если нужно, чтобы при отсутствии ресурса для запрошенного языка и региональных параметров просто возвращался ключ, не используйте файл ресурсов по умолчанию.
Создание файлов ресурсов с помощью Visual Studio
Если вы создаете в Visual Studio файл ресурсов, в имени которого не указаны язык и региональные параметры (например, Welcome.resx), Visual Studio создаст класс C# со свойством для каждой строки. В ASP.NET Core обычно требуется иное поведение. Как правило, файл ресурсов RESX по умолчанию (файл RESX без указания языка и региональных параметров) не используется. Мы рекомендуем создать файл RESX с указанием языка и региональных параметров (например, Welcome.fr.resx). При создании файла RESX с указанием языка и региональных параметров среда Visual Studio не создает файл класса.
Добавление других языков и региональных параметров
Каждое сочетание языка и региональных параметров (кроме языка по умолчанию) требует уникального файла ресурсов. Вы создаете файлы ресурсов для разных языков и языковых стандартов, создавая новые файлы ресурсов, в которых коды языков являются частью имени файла (например, en-us, fr-ca и en-gb). Эти коды помещаются между именем файла и расширением RESX , как в Welcome.es-MX.resx (испанский/Мексико).
Следующие шаги
Локализация приложения также включает следующие задачи:
- Сделайте содержимое приложения локализуемым.
- Реализация стратегии выбора языка или языка и региональных параметров для каждого запроса
Дополнительные ресурсы
- Поставщик языка и региональных параметров URL-адреса с помощью по промежуточного слоя в качестве фильтров в ASP.NET Core
- Применение RouteDataRequest CultureProvider глобально с по промежуточного слоя в качестве фильтров
- Глобализация и локализация в ASP.NET Core
- Сделать содержимое приложения ASP.NET Core локализуемым
- Стратегии выбора языка и языка и региональных параметров в локализованном приложении ASP.NET Core
- Устранение неполадок локализации ASP.NET Core
- Глобализация и локализация приложений .NET
- Проект Localization.StarterWeb, используемый в этой статье.
- Ресурсы в RESX-файлах
- Набор средств многоязычных приложений Майкрософт
- Локализация и универсальные шаблоны
Авторы: Рик Андерсон (Rick Anderson), Дэмиен Боуден (Damien Bowden), Барт Каликсто (Bart Calixto), Надим Афана (Nadeem Afana) и Хишам Бин Атея (Hisham Bin Ateya)
Одной из задач локализации приложения является предоставление локализованных строк в файлах ресурсов. В этой статье описывается работа с файлами ресурсов.
SupportedCultures и SupportedUICultures.
ASP.NET Core содержит две коллекции значений языка и региональных параметров, SupportedCultures а также SupportedUICultures. Объект CultureInfo для SupportedCultures определения результатов функций, зависимых от языка и региональных параметров, таких как дата, время, число и форматирование валют. SupportedCultures также определяет порядок сортировки текста, соглашения о регистре символов и способы сравнения строк. Дополнительные StringComparer.CurrentCulture сведения о том, как сервер получает язык и региональные параметры. Значение SupportedUICultures определяет то, какие строки переводов (в файлах RESX) ищет объект ResourceManager. Просто ResourceManager ищет строки, зависящие от языка и региональных параметров, которые определяются CurrentUICulture. Каждый поток в .NET имеет объекты CurrentCulture и CurrentUICulture. ASP.NET Core проверяет эти значения при обработке функций, зависящих от языка и региональных параметров. Например, если для текущего потока заданы язык и региональные параметры "en-US" (английский, США), метод DateTime.Now.ToLongDateString() выводит строку "Thursday, February 18, 2016", но если CurrentCulture имеет значение "ru-RU" (русский, Россия), выводится строка "четверг, 18 февраля 2016 г."
Файлы ресурсов
Файл ресурсов — это полезное средство для отделения локализуемых строк от кода. Переведенные строки на языках, отличных от языка по умолчанию, содержатся в отдельных файлах ресурсов с расширением RESX. Например, может потребоваться создать испанский файл ресурсов с именем Welcome.es.resx , содержащий переведенные строки. "es" — это код испанского языка. Чтобы создать этот файл ресурсов в Visual Studio, выполните указанные ниже действия.
В Обозреватель решений щелкните правой кнопкой мыши папку, содержащую файл ресурса, а затем нажмите кнопку "Добавить>новый элемент".
В поле Поиск установленных шаблонов введите слово "ресурс" и укажите имя файла.
Введите значение ключа (строку на исходном языке) в столбце Имя и переведенную строку в столбце Значение.
В Visual Studio отобразится файл Welcome.es.resx.
Именование файлов ресурсов
Имена ресурсов представляют собой полные имена типов соответствующего класса за исключением имени сборки. Например, ресурс на французском языке в проекте, главная сборка которого имеет имя LocalizationWebsite.Web.dll, для класса LocalizationWebsite.Web.Startup будет иметь имя Startup.fr.resx. Ресурс для класса LocalizationWebsite.Web.Controllers.HomeController будет иметь имя Controllers.HomeController.fr.resx. Если пространство имен целевого класса не совпадает с именем сборки, необходимо использовать полное имя типа. Например, в образце проекта ресурс для типа ExtraNamespace.Tools будет иметь имя ExtraNamespace.Tools.fr.resx.
В примере проекта ConfigureServices метод задает ResourcesPath значение Resources, поэтому относительный путь проекта для home французского файла ресурсов контроллера — Resources/Controllers.HomeController.fr.resx. Кроме того, для упорядочения файлов ресурсов можно использовать папки. Для контроллера home путь будет иметь значение Resources/Controllers/HomeController.fr.resx. Если параметр ResourcesPath не используется, файл RESX будет находиться в базовом каталоге проекта. Файл ресурса для HomeController будет иметь имя Controllers.HomeController.fr.resx. Выбор соглашения об именовании на основе точечной нотации или пути зависит от того, как следует упорядочивать файлы ресурсов.
| Имя ресурса | Точечная нотация или путь |
|---|---|
| Resources/Controllers.HomeController.fr.resx | Точки |
| Resources/Controllers/HomeController.fr.resx | Путь |
Файлы ресурсов, для которых используется директива @inject IViewLocalizer в представлениях Razor, следуют той же модели. Файлу ресурсов для представления может присваиваться имя на основе либо точечной нотации, либо пути. В файле ресурсов для представления Razor имитируется путь к связанному файлу представления. Если для ResourcesPath задано значение Resources, то файл ресурсов на французском языке, связанный с представлением Views/Home/About.cshtml, может иметь одно из следующих имен.
Resources/Views/Home/About.fr.resx
Resources/Views.Home.About.fr.resx
Если параметр ResourcesPath не используется, файл RESX для представления будет находиться в той же папке, что и представление.
RootNamespaceAttribute
Атрибут RootNamespaceAttribute предоставляет корневое пространство имен сборки, если корневое пространство имен сборки отличается от имени сборки.
Предупреждение
Это может произойти, если имя проекта — недопустимый идентификатор .NET. Например, my-project-name.csproj будет использовать корневое пространство имен my_project_name и имя сборки my-project-name, что повлечет эту ошибку.
Если корневое пространство имен сборки отличается от имени сборки
- Локализация не работает по умолчанию.
- Локализация завершается сбоем из-за метода поиска ресурсов в сборке.
RootNamespace— это значение во время сборки, которое недоступно выполняющемуся процессу.
Если RootNamespace отличается от AssemblyName, включите следующее в файл AssemblyInfo.cs (со значениями параметров, замененными фактическими значениями).
using System.Reflection;
using Microsoft.Extensions.Localization;
[assembly: ResourceLocation("Resource Folder Name")]
[assembly: RootNamespace("App Root Namespace")]
Приведенный выше код обеспечивает успешное разрешение RESX-файлов.
Резервный язык и региональные параметры
При поиске ресурса локализации использует резервный язык и региональные параметры. Если запрошенный язык и региональные параметры не найдены, используется родительский язык и региональные параметры. В стороне CultureInfo.Parent свойство представляет родительский язык и региональные параметры. Это обычно (но не всегда) означает удаление национального знака из кода языка и культуры. Например, диалект испанского в Мексике — es-MX. Родительский элемент "es" (испанский) не относится к той или иной стране.
Допустим, сайт получает запрос на ресурс "Приветствие" с использованием языка и региональных параметров fr-CA. Система локализации ищет в следующих ресурсах по порядку и выбирает первое совпадение:
- Welcome.fr-CA.resx
- Welcome.fr.resx
- Welcome.resx (если
NeutralResourcesLanguage— fr-CA)
Если вы удалите указатель языка и региональных параметров ".fr" и при этом задан французский язык и региональные параметры, будет считан файл ресурсов по умолчанию и строки локализуются. Диспетчер ресурсов назначает ресурс по умолчанию или резервный ресурс на тот случай, когда соответствия запрошенному языку и региональным параметрам не найдено. Если нужно, чтобы при отсутствии ресурса для запрошенного языка и региональных параметров просто возвращался ключ, не используйте файл ресурсов по умолчанию.
Создание файлов ресурсов с помощью Visual Studio
Если вы создаете в Visual Studio файл ресурсов, в имени которого не указаны язык и региональные параметры (например, Welcome.resx), Visual Studio создаст класс C# со свойством для каждой строки. В ASP.NET Core обычно требуется иное поведение. Как правило, файл ресурсов RESX по умолчанию (файл RESX без указания языка и региональных параметров) не используется. Мы рекомендуем создать файл RESX с указанием языка и региональных параметров (например, Welcome.fr.resx). При создании файла RESX с указанием языка и региональных параметров среда Visual Studio не создает файл класса.
Добавление других языков и региональных параметров
Каждое сочетание языка и региональных параметров (кроме языка по умолчанию) требует уникального файла ресурсов. Вы создаете файлы ресурсов для разных языков и языковых стандартов, создавая новые файлы ресурсов, в которых коды языков являются частью имени файла (например, en-us, fr-ca и en-gb). Эти коды помещаются между именем файла и расширением RESX , как в Welcome.es-MX.resx (испанский/Мексико).
Следующие шаги
Локализация приложения также включает следующие задачи:
- Сделайте содержимое приложения локализуемым.
- Реализация стратегии выбора языка или языка и региональных параметров для каждого запроса
Дополнительные ресурсы
- Глобализация и локализация в ASP.NET Core
- Сделать содержимое приложения ASP.NET Core локализуемым
- Стратегии выбора языка и языка и региональных параметров в локализованном приложении ASP.NET Core
- Устранение неполадок локализации ASP.NET Core
- Глобализация и локализация приложений .NET
- Проект Localization.StarterWeb, используемый в этой статье.
- Ресурсы в RESX-файлах
- Набор средств многоязычных приложений Майкрософт
- Локализация и универсальные шаблоны
ASP.NET Core