Локализация

Локализация приложения позволяет пользователю видеть надписи в интерфейсе приложения на том языке, который он использует для работы (порядок определения языка локализации).

Локализованные строки могут использоваться в таких элементах, как:

• свойство Представление элемента проекта Описание подсистемы;
• представление реквизитов справочников, регистров сведений и планов обмена;
• представление команд открытия автоматических форм элементов проекта, а также заголовки этих форм;
• свойство Представление элементов перечисления и полей структур;
• описание и шаблон представления события журнала событий;
• строки, формируемые в коде.

Языки локализации и язык по умолчанию

Чтобы локализация приложения стала возможной, в элементе Описание проекта должны быть заданы языки локализации и один из них должен быть указан как язык по умолчанию. Например:

Пример YAML-файла элемента «Описание проекта»

Ид: 0195ec77-ce86-73ba-aecc-4d840e00d78f
Версия: 1.0
Имя: ПримерЛокализации
Поставщик: e1c
Представление: Пример локализации
ПредставлениеПоставщика: e1c
РежимСовместимости: 9.0
ЯзыкРазработки: Русский
ЯзыкПоУмолчанию: Русский
ЯзыкиЛокализации:
    - Русский
    - Английский

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

Элемент проекта вида «ЛокализованныеСтроки»

Используйте элемент проекта вида ЛокализованныеСтроки для хранения строк, которые должны быть переведены на другие языки. Данный элемент проекта содержит ключи (идентификаторы) локализуемых строк и их значения на языке по умолчанию. Блоки идентификаторов разделены на две секции:

• Строки

  Строки можно использовать в описании компонентов интерфейса и элементов проекта, а также в коде.

• Шаблоны

  Шаблоны можно использовать только в коде. В них можно подставлять значения переменных.

Пример:

ЛокализованныеСтроки.yaml

ВидЭлемента: ЛокализованныеСтроки
Ид: 8e1bb67c-bd81-4838-b9fc-fac9520bffcc
Имя: ЛокализованныеСтроки
ОбластьВидимости: ВПодсистеме
Строки:
    Код: Код
    Наименование: Наименование
    Описание: Описание
    ПользовательПоУмолчанию: Пользователь по умолчанию
    ИдТокена: Идентификатор токена
    Регион: Регион
    Uri: URI
    Хост: Хост
Шаблоны:
    ТекущееВремя: "Текущее время: %0"

Чтобы создать элемент проекта ЛокализованныеСтроки, используйте один из описанных ниже способов.

Автоматическая генерация локализованных строк

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

   

2. «1С:Шина» отобразит диалог Локализовать строки. Данный диалог содержит таблицу ключей и значений локализуемых строк, автоматически сгенерированных для всех объектов, поддерживающих локализацию.

   

3. В поле Новые локализованные строки введите имя элемента проекта ЛокализованныеСтроки.

   Если в проекте уже есть локализованные строки, диалог покажет список доступных (видимых для выбранных локализуемых объектов) элементов проекта вида ЛокализованныеСтроки. Вы можете выбрать один из этих элементов, чтобы добавить к нему новые строки.

   

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

   

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

5. Нажмите Применить. «1С:Шина» создаст элемент проекта ЛокализованныеСтроки с заданным именем. Если для проекта указаны другие языки локализации, «1С:Шина» также добавит раздел локализации.

Создание локализованных строк вручную

1. Наведите мышку на нужную подсистему и нажмите на знак плюса.

2. В открывшемся окне выберите элемент проекта Локализованные строки.

   

3. Введите имя создаваемого элемента проекта.

4. «1С:Шина» предложит вам добавить файлы локализации на других языках. Нажмите Создать, чтобы автоматически добавить раздел локализации к проекту. Если вы хотите создать этот раздел позднее, нажмите Отменить.

   

5. Укажите ключи и значения локализуемых строк в панели свойств элемента проекта ЛокализованныеСтроки.

   

Раздел проекта «Локализация»

Чтобы сохранить в проекте значения локализуемых строк на другом языке (язык может быть только тот, который указан в описании проекта в свойстве ЯзыкиЛокализации), вы должны добавить к проекту раздел Локализация. Если вы не сделали этого при создании элемента проекта ЛокализованныеСтроки, вы можете добавить этот раздел следующим образом:

1. Наведите мышку на элемент проекта ЛокализованныеСтроки и нажмите на знак плюса.

2. В открывшемся окне выберите язык, на который нужно перевести строки.

   

«1С:Шина» создаст раздел локализации, содержащий пустой элемент локализации. Имя элемента локализации будет совпадать с именем элемента проекта вида ЛокализованныеСтроки.

В результате проект будет иметь следующую структуру:

Элемент локализации должен содержать только секции с именами и значениями локализуемых строк. Например:

ЛокализованныеСтроки.yaml

Строки:
    Код: Code
    Наименование: Name
    Описание: Description
    ПользовательПоУмолчанию: Default user
    ИдТокена: Token ID
    Регион: Region
    Uri: URI
    Хост: Host
Шаблоны:
    ТекущееВремя: "Current time: %0"

Вы можете указать перевод строк в панели свойств элемента локализации:

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

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

• в диалоге Локализовать строки:

  

• в панели свойств локализуемого объекта:

  

Использование в значениях свойств элементов проекта

«1С:Шина» позволяет вам задавать идентификаторы локализованных строк в панели свойств элементов проекта. Для этого активируйте настройку Использовать локализованное значение для нужного свойства. В открывшемся меню выберите имя элемента проекта ЛокализованныеСтроки, содержащего нужную строку, и ключ строки.

Если необходимо, вы можете отредактировать значение выбранной строки или создать новую строку. Для этого нажмите Создать новую локализованную строку и укажите ключ и значение строки в открывшемся диалоговом окне.

В случае использования локализованной строки в значении свойства элемента в YAML необходимо указать идентификатор строки, начиная с символа «$». Идентификатор локализованной строки состоит из трех частей и выглядит следующим образом: $<Имя подсистемы>::<Имя элемента проекта локализованных строк>.<Имя локализованной строки в данном элементе>.

Пример:

ИнформационныеСистемы.yaml

ВидЭлемента: Справочник
Ид: 358e7fac-d6d0-4ca0-ae4a-e59eb913f3cc
Имя: ИнформационныеСистемы
ОбластьВидимости: ВПроекте
НастройкиТипов:
    Справочник.Объект:
        Контракты:
            - СправочникИнформационныхСистем.Объект
Реквизиты:
    -
        Имя: Наименование
        Длина: 255
        Представление: $ЛокализованныеСтроки.Наименование
    -
        Имя: Код
        Длина: 36
        Представление: $ЛокализованныеСтроки.Код
        Тип: Строка

совет

Если вам необходимо задать строку, начинающуюся с символа «$», экранируйте данный символ с помощью еще одного символа «$».

Правила разрешения коллизий

• Если локализованные строки находятся в той же подсистеме, где и вызываются, то указание подсистемы после «$» необязательно.
• Если подсистема с нужными локализованными строками импортируется, то указание подсистемы после «$» необязательно.
• Коллизии локализованных строк с текущей и импортируемыми подсистемами разрешается в пользу локальных локализованных строк.
• Необходимо указывать нелокальную подсистему в идентификаторе локализованных строк, если подсистема используется, но не импортируется.

Использование в коде

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

Сообщить(ЛокализованныеСтроки.ТекущееВремя("${Время.Сейчас()|ч:мм}"))

В этом примере используется строка-шаблон с именем ТекущееВремя, в которую подставляется отформатированное представление текущего времени.

При запуске с русскими региональными установками «1С:Шина» выведет строку на русском языке:

Текущее время: 5:38

При запуске с английскими региональными установками он выведет строку на английском языке:

Current time: 5:38

Локализация строк в коде модуля

«1С:Шина» позволяет быстро преобразовать строки, используемые в модуле, в локализованные.

• Для локализации одной строки используйте механизм быстрых исправлений.

  

• Для локализации всех строк модуля щелкните по нему правой кнопкой мыши и выберите пункт Локализовать строки в контекстном меню.

«1С:Шина» откроет диалог Локализовать строки, содержащий автоматически сгенерированные ключи и значения локализуемых строк. При необходимости отредактируйте эти значения и нажмите Применить.

Не локализуются:

• параметры и возвращаемые значения методов (если они имеют тип Строка), а также параметры событий;
• массивы строк.

Получение текущего языка локализации

Вы можете получить значение текущего языка локализации с помощью статического метода Язык.Текущий():

@НаСервере @ДоступноСКлиента
статический метод ЯзыкИнтерфейса(): Строка
    возврат Язык.Текущий().Код
    // Вернет строку "ru", если текущий язык — русский
    // Вернет строку "en", если текущий язык — английский
;

Переключение языка через «КонтекстЛокализации»

Тип КонтекстЛокализации позволяет временно изменить язык системы. Пока контекст открыт, используется указанная при открытии локаль. После его закрытия автоматически возвращается исходная локаль.

В методе Открыть() контекста локализации можно указать два параметра:

• ЛокальОтображения — определяет язык интерфейса, сообщений и локализованных строк.

• ЛокальФорматирования — управляет правилами отображения дат, чисел и других значений.

Использование локали

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

если Локаль.ТекущаяЛокальОтображения().КодРегиона == "en-US"
    // Отображаем предупреждение для указанного региона 
    Сообщить("This service is not available in your region")
;

Как запустить приложение с другим языком

Существует порядок, по которому «1С:Шина» определяет, какой язык нужно выбрать для конкретного пользователя. Этот порядок описан в следующем разделе.

Чтобы проверить, как работает приложение на другом языке, запустите его и выберите нужный язык в форме входа в приложение:

Вы также можете изменить язык в самом приложения с помощью команды Переключить язык на панели действий:

Порядок определения текущих региональных установок при подключении пользователя

• Параметр locale, передаваемый в URL. Например:

  http://localhost:9090/applications/esb-app?locale=en_EN

  Если параметр не указан или не поддерживается «1С:Шиной», то используется следующий пункт.

• Поддерживаемый приложением язык из списка предпочтительных языков браузера. Список языков браузера берется из значения HTTP-заголовка Accept-Language. В случае неудачи используется следующий пункт. Возможные причины неудачи:

  • В списке языков браузера нет ни одного языка из поддерживаемых «1С:Шиной».
  • Браузер устарел, и у него нельзя узнать предпочтительные языки.

• Локаль приложения (в панели управления Приложения ⟶ Название приложения ⟶ Настройки ⟶ Общие ⟶ Локаль), которая задается при создании приложения. Если локаль приложения не указана, тогда используется следующий пункт.

• ЯзыкПоУмолчанию из файла описания проекта.