Общие сведения о локализации ресурсов для библиотек компонентов

Статья
10/22/2014

Обновлен: Ноябрь 2007

Локализация — это процесс настройки приложения для работы в заданной языковой среде. Средства AJAX в ASP.NET поддерживают следующие модели локализации для работы с клиентским сценарием:

Модель ресурсов .NET Framework с раcширенной поддержкой локализованных ресурсов, связанных с компонентами ECMAScript (JavaScript). Данная модель предусматривает внедрение файлов сценариев и локализованных ресурсов сценариев в комплекте сборок, организованном по схеме типа "звезда" (иными словами, с использованием вспомогательных сборок). Затем можно выборочно использовать клиентские сценарии и ресурсы, включенные в эту модель, для конкретных языков и регионов. В этой модели имеется единый базовый код для поддержки многих языков и региональных параметров.
Статические (автономные) файлы JavaScript на диске. В этой модели локализованные файлы не внедряются в сборку, а группируются в отдельном каталоге как JS-файлы.
Обновление сценариев и ресурсов, внедренных в сборку, с помощью статических файлов JavaScript. Эта модель позволяет обеспечить дополнительную поддержку локализации для внедренных сценариев и внедренных ресурсов, при этом нет необходимости вносить изменения в исходную сборку.

В этом разделе содержатся следующие подразделы:

Сценарии
Базовые сведения
Локализация клиентских сценариев и ресурсов сценариев в сборках
Локализация файлов сценариев и их ресурсов
Управление сценариями в централизованном расположении с помощью элемента управления ScriptManager
Примеры кода
Ссылки на классы

Сценарии

Возможности AJAX в ASP.NET позволяют обеспечить локализацию клиента для разработчиков страниц и компонентов. Разработчики страниц, как правило, локализуют следующие компоненты:

Сообщения исключений, которые создает непосредственно ASP.NET AJAX или библиотеки компонентов с учетом языковых настроек обозревателя.
Пользовательский интерфейс для элементов управления, например строки для свойства Text элемента управления Button.
Значения общих свойств серверных элементов управления ASP.NET AJAX.
Значения для свойств объектов клиентских сценариев и компонентов, таких как компоненты, поведения и элементы управления без визуального представления.

Разработчики компонентов, как правило, используют возможности локализации в следующих целях:

Локализация ресурсов, на которые ссылается код библиотек JavaScript (JS-файлы). Эти локализованные ресурсы можно разворачивать в отдельных установках, не перестраивая при этом основную сборку или библиотеку сценариев.
Предоставление локализуемых свойств серверных элементов управления, которые сопоставлены со свойствами клиентских объектов.

Базовые сведения

Возможности AJAX в ASP.NET разработаны на основе локализационной модели ASP.NET 2.0. Она обеспечивает дополнительную поддержку локализованных файлов сценариев, внедренных в сборку или предоставляемых в виде статических JS-файлов на диске.

Те, кто не знаком с локализационной моделью ASP.NET, могут найти информацию о ней в следующих разделах:

Локализация клиентских файлов сценариев и ресурсов сценариев в сборках

В целях локализации ASP.NET AJAX использует модель ресурсов .NET Framework. Для упаковки и развертывания локализованных ресурсов, которые могут постепенно обновляться, данная модель использует схему типа "звезда". В центре "звезды" находится основная сборка, в которой содержится нелокализуемый выполняемый код. Данный код включает в себя серверный код .NET Framework и любой код JavaScript в JS-файлах, внедренных в сборку в качестве ресурса.

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

Ресурсы, локализованные с учетом того или иного языка и региональных параметров, как правило, регистрируются в виде пары имя/значение в RESX-файлах. (Данные RESX-файлы можно скомпилировать в файлы .resources). Имя предоставляет доступ к сведениям в коде, а значение представляет собой локализованный (переведенный на тот или иной язык) термин, изображение или другой элемент, соответствующий заданному имени. При построении сборки для RESX-файла создается тип, предоставляющий имена в виде полей, которые позволяют осуществлять программный доступ к значениям. (Пользователь задает имя для созданного типа как часть свойств сборки согласно приведенному ниже описанию).

В модели "звезда" каждый "луч" ведет к вспомогательной сборке, которая содержит ресурсы для отдельного языка и региональных параметров. Вспомогательные сборки не содержат код, выполняемый сервером. Они содержат только созданный тип, который предоставляет программный доступ к значениям ресурсов, связанным с данным языком и региональными параметрами.

Данная модель предоставляет следующие возможности:

После развертывания сборки можно добавлять ресурсы для новых языков и региональных параметров, развертывая новые вспомогательные сборки. Разработка ресурсов для конкретных языков и региональных параметров может занять дополнительное время. Следовательно, модель позволяет сначала завершить создание основного приложения, а затем доставить дополнительные ресурсы для конкретного языка и региональных параметров.
Вспомогательные сборки приложения можно обновлять, не выполняя повторную компиляцию основной сборки.
Приложение может загрузить только вспомогательную сборку для конкретного языка и региональных параметров, при этом не нужно будет выгружать и загружать повторно основную сборку. Такой подход существенно снижает затраты системных ресурсов.

Дополнительные сведения о создании файлов ресурсов ASP.NET см. в разделах Практическое руководство. Создание файлов ресурсов для веб-узлов ASP.NET и Локализация веб-страниц ASP.NET с использованием ресурсов.

Дополнительные сведения о работе с генератором файлов ресурсов .NET Framework (средством Resgen.exe) см. в разделе Генератор файлов ресурсов (Resgen.exe). Это средство позволяет преобразовывать файлы TXT и RESX в двоичные файлы с расширением RESOURCES, которые могут быть связаны со сборками.

Организация локализованных основных и вспомогательных сборок

Модель "звезда" можно использовать для локализации приложения, которое содержит файлы JavaScript (JS-файлы). Как правило, сборка организуется по той же схеме, что и любое локализуемое приложение ASP.NET.

Чтобы управлять файлами JavaScript для веб-приложения ASP.NET, оснащенного технологией AJAX, необходимо написать код JavaScript, в котором локализуемые строки или другие элементы не были бы заданы жестко. В результате там, где в код JavaScript должны подставляться локализуемые значения, будет возникать поле из типа, задаваемого файлом ресурсов.

Обычно основная сборка содержит следующие элементы:

Файлы JavaScript, выполняющие задачи приложения и запрограммированные таким образом, чтобы вместо жестко заданных ресурсов можно было бы использовать локализованные. Дополнительно сборка может содержать отладочные версии файлов JavaScript.
При необходимости — ресурсы (файлы RESX или RESOURCES) для отдельного нейтрального языка и региональных параметров, которые являются резервными параметрами для приложения.
При необходимости — отладочные версии ресурсов нейтрального языка и региональных параметров. Отладочная версия файла ресурсов содержит любые дополнительные пары имя/значение, которые требуются для отладочных версий файлов JavaScript.

Как правило, вспомогательная сборка содержит локализованные ресурсы для отдельного языка и региональных параметров, используемых в приложении ASP.NET. (Для резервного языка и региональных параметров вспомогательных сборок не требуется). Ресурсы для отдельного языка и региональных параметров создаются в отдельном файле ресурсов (файлы RESX или RESOURCES), а затем компилируются в единую вспомогательную сборку.

Примечание.
С помощью ASP.NET можно создать пользовательский набор языковых и региональных параметров для пользовательского интерфейса и присвоить этому набору уникальное имя. Однако, как правило, имена для наборов языковых и региональных параметров создаются по единообразной схеме на основе стандартных обозначений ISO, в которых две первые строчные буквы обозначают язык, а две прописные — страну или регион. Примерами являются es-MX (испанский — Мексика), es-CO (испанский — Колумбия) и fr-CA (французский — Канада). Полный список названий языков и региональных параметров см. в общих сведениях о классе System.Globalization.CultureInfo.

С помощью ASP.NET можно создать пользовательский набор языковых и региональных параметров для пользовательского интерфейса и присвоить этому набору уникальное имя. Однако, как правило, имена для наборов языковых и региональных параметров создаются по единообразной схеме на основе стандартных обозначений ISO, в которых две первые строчные буквы обозначают язык, а две прописные — страну или регион. Примерами являются es-MX (испанский — Мексика), es-CO (испанский — Колумбия) и fr-CA (французский — Канада). Полный список названий языков и региональных параметров см. в общих сведениях о классе System.Globalization.CultureInfo.

Имена локализованных внедренных файлов сценариев

В отношении имен локализованных файлов сценариев, которые внедряются в качестве ресурсов, приняты следующие правила:

scriptname_noextension.[debug].[UI culture identifier].[resources|resx]

Имя отладочной версии файла обязательно должно содержать часть ".debug". Имя окончательной версии не должно содержать эту часть.

В следующей таблице приведены примеры имен, созданных в соответствии с правилами. В качестве примеров приведены отладочные и окончательные версии внедренного файла сценария. Также в таблице приведены связанные с ним отладочная и окончательная версии ресурсов.

Sample.js
Окончательная версия файла сценария для нейтрального языка и региональных параметров, внедренная в основную сборку.
Sample.debug.js
Отладочная версия файла сценария для нейтрального языка и региональных параметров, внедренная в основную сборку.
Sample.fr-FR.resources
Окончательная версия ресурсов, связанных с файлом сценария Sample.js, который локализован для определенного языка и региональных параметров пользовательского интерфейса. Эти ресурсы включаются в состав вспомогательной сборки.
Sample.debug.fr-FR.resources
Отладочные ресурсы, связанные с файлом сценария Sample.debug.js, который локализован для определенного языка и региональных параметров пользовательского интерфейса. Эти ресурсы включаются в состав вспомогательной сборки, которая также содержит файл Sample.fr-FR.resources.

Эти правила не являются строго обязательными для имен файлов сценария, внедренных в сборки и имен файлов ресурсов. Это связано с тем, что для сопоставления типа, создаваемого для ресурса, с именем ресурса используется атрибут сборки.

Локализация отладочных ресурсов сценария

При работе в режиме отладки во время выполнения ASP.NET объединяет окончательную версию ресурсов для файлов сценариев с другими отладочными ресурсами. Получившееся в результате сочетание отправляется в обозреватель. Следовательно, при создании файлов ресурсов для отладочных версий сценариев, достаточно только определить пары имя/значение, которые еще не включены в окончательные файлы ресурсов сценария. Согласно правилам, имена отладочных версий сценариев и ресурсов сценариев почти полностью совпадают с именами окончательных версий за исключением того, что в именах отладочных версий после имени файла сценария добавляется часть ".debug".

Установка атрибутов сборки для локализованных сценариев и локализованных ресурсов, связанных со сценариями

Чтобы задать способ управления файлами во время построения сборки, необходимо добавить атрибуты в файл AssemblyInfo (AssemblyInfo.vb или AssemblyInfo.cs).

Примечание.
В среде Visual Studio файл AssemblyInfo.vb для проектов, написанных на Visual Basic, находится в узле Мой проектобозревателя решений. Если в узле Мой проект не отображаются файлы, в меню Проект выберите пункт Показать все файлы. Для проектов, написанных на C#, файл AssemblyInfo.vb находится в узле Свойстваобозревателя решений.

В среде Visual Studio файл AssemblyInfo.vb для проектов, написанных на Visual Basic, находится в узле Мой проектобозревателя решений. Если в узле Мой проект не отображаются файлы, в меню Проект выберите пункт Показать все файлы. Для проектов, написанных на C#, файл AssemblyInfo.vb находится в узле Свойстваобозревателя решений.

В ASP.NET можно пометить ресурсы для приложения с помощью класса WebResourceAttribute. Чтобы внедрить файлы JavaScript в сборку, необходимо с помощью этого атрибута пометить JS-файлы как веб-ресурсы.

Добавить файлы ресурсов для внедренных файлов JavaScript можно с помощью класса ScriptResourceAttribute. Этот атрибут определяет текстовые ресурсы непосредственно как ресурсы для файлов JavaScript.

Примечание.
Класс ScriptResourceAttribute позволяет определять только текстовые ресурсы для файлов JavaScript. Чтобы сопоставить файл (двоичный) локализованного изображения с языком и региональными параметрами, необходимо сохранить его URL-адрес как локализованный ресурс, который мог бы быть разрешен и загружен сценарием.

Класс ScriptResourceAttribute позволяет определять только текстовые ресурсы для файлов JavaScript. Чтобы сопоставить файл (двоичный) локализованного изображения с языком и региональными параметрами, необходимо сохранить его URL-адрес как локализованный ресурс, который мог бы быть разрешен и загружен сценарием.

В приведенном ниже примере показано, каким образом можно определить внедренные сценарии и связанные с ними ресурсы с помощью атрибутов сборок.

' Indicates that neutral fallback resources are retrieved from 
' the main assembly named MainAssembly.
<assembly: NeutralResourcesLanguageAttribute("en-US",
  UltimateResourceFallbackLocation.MainAssembly)>

' Defines embedded scripts as Web resources.
<assembly:WebResource("Sample.js", "text/javascript")>
<assembly:WebResource("Sample.debug.js", "text/javascript")>

' Defines the script resources for the scripts and their types.
<assembly:ScriptResource("Sample.js", "Sample.resources", 
  "Sample.Res")>
<assembly:ScriptResource("Sample.debug.js", "Sample.debug.resources", 
  "Sample.Res")>

// Indicates that neutral fallback resources are retrieved from 
// the main assembly named MainAssembly.

[assembly: NeutralResourcesLanguageAttribute("en-US",
  UltimateResourceFallbackLocation.MainAssembly)]

// Defines embedded scripts as Web resources.
[assembly:WebResource("Sample.js", "text/javascript")]
[assembly:WebResource("Sample.debug.js", "text/javascript")]

// Defines the script resources for the scripts and their types.
[assembly:ScriptResource("Sample.js", "Sample.resources", 
  "Sample.Res")]
[assembly:ScriptResource("Sample.debug.js", "Sample.debug.resources", 
  "Sample.Res")]

В данном примере в основной сборке с именем MainAssembly содержится внедренная окончательная версия клиентского файла сценария с именем Sample.js. В сборке также содержится соответствующая отладочная версия с именем Sample.debug.js. JS-файлы определяются как ресурсы с помощью атрибута WebResourceAttribute.

Атрибут сборки NeutralResourcesLanguageAttribute позволяет указать основную сборку в качестве резервного языка и региональных параметров. Дополнительные сведения см. в разделе Языки нейтральных ресурсов для локализации и общих сведениях о классе System.Resources.NeutralResourcesLanguageAttribute.

Ресурсы, используемые файлами сценария, определяются с помощью атрибута ScriptResourceAttribute. Файлы Sample.resources и Sample.debug.resources содержат значения ресурсов для файлов Sample.js и Sample.debug.js, соответственно.

Тип с именем Sample.Res создается как для окончательной, так и для отладочной версии ресурсов сценария. Этот тип используется в коде JavaScript для доступа к локализованным значениям. В процессе построения для окончательной и отладочной версии создается только один (единый) тип. В режиме отладки ресурсы окончательной версии объединяются с дополнительными ресурсами отладочной версии.

Дополнительные сведения о создании информационных файлов сборки и метаданных сборки, которые требуются для версионных сборок см. в разделе Практическое руководство. Создание сборок с поддержкой версий для предварительно скомпилированных веб-узлов.

Локализация файлов сценариев и их ресурсов

Библиотеку сценариев можно организовать в виде локализованных файлов статического сценария (JS-файлов) на диске вместо того, чтобы внедрять файлы сценария в сборки. Разработчики страниц могут добавить ссылку на сценарий с помощью класса ScriptReferenceCollection.

В модели статического файла сценария не предусмотрено отдельных файлов RESX или RESOURCES, которыми можно было бы автоматически управлять как ресурсами для файлов JavaScript. Имеются только JS-файлы, каждый из которых соответствует одному набору языкового стандарта и региональным параметрам пользовательского интерфейса. Фактически каждый JS-файл представляет полную версию кода JavaScript для данного языкового стандарта. В стандартной ситуации для управления локализованными файлами сценария в этой модели рекомендуется использовать одну и ту же логику JavaScript в каждом JS-файлы. Как и в модели с внедренными сборками код JavaScript вызывает тип для извлечения локализованных значений ресурсов. Единственное различие состоит в том, что пользователь должен предоставить тип, содержащий локализованные значения, так как он не создается автоматически. Например, JS-файл для каждого языкового стандарта может содержать как код приложения, так и класс, определяющий поля, которые содержат локализованные значения. В каждом отдельном JS-файле этот класс будет содержать значения на разных языках.

Примечание.
В модели статического файла сценария код JavaScript приложения, содержащийся в JS-файлах, может потерять синхронизацию с кодом, который внедрен в файле JavaScript. Это происходит потому, что в каждом файле сценария содержится копия кода. Во избежание сбоев при управлении версиями, которые могут возникнуть в связи с наличием продублированного кода, можно оставить одну копию файлов ресурсов JavaScript и создать локализованные типы ресурсов в других файлах. Затем окончательные объединенные файлы будут созданы в процессе построения приложения.

В модели статического файла сценария код JavaScript приложения, содержащийся в JS-файлах, может потерять синхронизацию с кодом, который внедрен в файле JavaScript. Это происходит потому, что в каждом файле сценария содержится копия кода. Во избежание сбоев при управлении версиями, которые могут возникнуть в связи с наличием продублированного кода, можно оставить одну копию файлов ресурсов JavaScript и создать локализованные типы ресурсов в других файлах. Затем окончательные объединенные файлы будут созданы в процессе построения приложения.

Для сопоставления локализованных статических файлов сценария с их языком и региональными параметрами пользовательского интерфейса название языка и региональных параметров пользовательского интерфейса добавляется к имени файла, точно так же, как это происходит с внедренными ресурсами и сборкой. Например, внедренный клиентский файл сценария, который является нейтральным по отношению к французскому языку, будет иметь имя Sample.fr.js а ресурс JavaScript, связанные с канадским региональным стандартом французского языка будет иметь имя Sample.fr-CA.js.

Локализованные сценарии отладки в модели статического файла сценария

В модели статического файла сценария локализованные ресурсы, на которые ссылается сценарий, как правило, определяются как тип в отдельном JS-файле. Отладочная версия файла сценария организована аналогичным образом, однако в ней как тип в отдельном файле определяются и окончательные локализованные ресурсы, и дополнительные ресурсы отладки. Имена отладочных версий сценариев и соответствующих им окончательных версий почти полностью совпадают за исключением того, что в имена отладочных версий добавляется часть ".debug".

Управление сценариями с помощью элемента управления ScriptManager

Элемент управления ScriptManager позволяет управлять статическими сценариями, которые размещены в главном каталоге на диске. Для этого необходимо разместить все версии файлов сценария, то есть окончательные и отладочные версии всех локализованных файлов, в одной папке. В следующем примере показана структура каталога для библиотеки статического файла сценария:

SampleNamespace/

1.0.0.0/

Sample.js

Sample.debug.js

Sample.de-DE.js

Sample.debug.de-DE.js

Sample.fr-FR.js

Sample.debug.fr-FR.js

В данном примере все файлы сценария размещены в папке, которая названа по версии библиотеки сценариев (1.0.0.0). Данная папка, предназначенная для конкретной версии, в свою очередь в папке, которая названа так же, как и пространство имен библиотеки. Если организовать библиотеку сценариев в папках по пространству имен и по версиям, это позволит обеспечить некоторые возможности управления версиями в библиотеке. Это также позволит избежать конфликтов между именами сценариев в разных библиотеках. Кроме того, такая организация позволит объектам, которые используют библиотеки, определить к какой библиотеке или к какой версии библиотеки принадлежит тот или иной файл.

О роли элемента управления ScriptManager в локализации

Элемент управления ScriptManager выполняет следующие функции во время работы с локализованными сценариями и их ресурсами:

Позволяет определять, какие языки и региональные параметры пользовательского интерфейса, в том числе созданные пользователем, поддерживаются.
Интерпретирует атрибут сборки, связанной с конкретным языком и региональными параметрами и автоматически определяет язык и региональные параметры интерфейса обозревателя (если они заданы). Затем элемент управления выполняет чтение локализованного или резервного сценария и ресурсов из сборки. В режиме отладки элемент управления пытается загрузить ресурс сценария, в котором содержится правильное имя языка и региональных стандартов пользовательского интерфейса, и строку ".debug" в имени файла, как например в файле Sample.debug.fr-FR.resources.
Создает URL-адреса, указывающие на соответствующие сценарии и на их локализованные ресурсы. Чтобы обеспечить дополнительный уровень защиты, элемент управления шифрует URL-адрес.
Определяет, будет ли выполняться сжатие сценария или его ресурса, исходя из параметра созданного URL-адреса.
Добавляет отметку времени в сборку, в которой содержатся внедренные сценарии, чтобы обозреватель не выполнял кэширование сценариев вслепую.

Дополнительные сведения см. в обзоре класса ScriptManager.

В следующем примере показана часть веб-страницы, на которой элемент управления ScriptManager используется для регистрации клиентского элемента управления, размещенного в сборке. Для регистрации внедренного сценария используются свойства Assembly и Name.

<%@ Register TagPrefix="Samples" Namespace="DemoControls" 
  Assembly=" SampleAssembly" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
  <title>ScriptReference</title>
</head>
<body>
  <form id="form1" runat="server">
    <div>
      <asp:ScriptManager ID="ScriptManager1" runat="server">
        <Scripts>
          <asp:ScriptReference Assembly="SampleAssembly"
              Name="DemoControls.SampleControl.js" />
        </Scripts>
      </asp:ScriptManager>

      <!-- Additional markup here. -->

    </div>
  </form>
</body>

Примеры кода

В следующих разделах приведены примеры кода, показывающие, каким образом можно работать с файлами JavaScript и ресурсами.

Практические и пошаговые руководства

Ссылки на классы

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

ScriptManager
Обеспечивает управление компонентами AJAX, частичную отрисовку страницы, клиентские запросы и ответы сервера на серверных страницах ASP.NET.
ScriptReference
Предоставляет API для регистрации файлов JavaScript, которые необходимо использовать на веб-странице. Это могут быть как файлы, внедренные в сборку, так и файлы, размещенные на диске.
ScriptReferenceCollection
Предоставляет доступ к объектам ScriptReference, которые представляют файлы клиентского сценария.

См. также

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