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

Visual Studio 2010

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

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

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

  • Статические (автономные) файлы JavaScript на диске. В этой модели локализованные файлы не внедряются в сборку, а группируются в отдельном каталоге как JS-файлы.

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

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

Возможности 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), а затем компилируются в единую вспомогательную сборку.

Bb398937.alert_note(ru-ru,VS.100).gifПримечание.

С помощью 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).

Bb398937.alert_note(ru-ru,VS.100).gifПримечание.

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

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

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

Bb398937.alert_note(ru-ru,VS.100).gifПримечание.

Класс 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")]

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

Bb398937.alert_note(ru-ru,VS.100).gifПримечание.

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

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

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

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

Элемент управления 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, которые представляют файлы клиентского сценария.

Показ: