i18n

Библиотека для локализации приложений на OneScript.

Установка

opm install i18n

Описание

• 1. Пакеты ресурсов
  • 1.1. Форматы ресурсов
  • 1.2. Рекомендуемая организация ресурсов
  • 1.3. Правила наименования файлов ресурсов
  • 1.4. Механизм поиска файлов ресурсов пакета
• 2. Глобальные локали
• 3. Встраивание в код приложения
  • 3.1. Инициализация
  • 3.2. Работа с пакетами ресурсов
  • 3.3. Работа с ресурсами
  • 3.4. Шаблонизация с автоподстановкой
• 4. Публичный интерфейс

Пакеты ресурсов

Пакеты ресурсов служат контейнерами для хранения специфичных для локали объектов: переводов текстов, шаблонов сообщений, форматов данных и настроек. Ресурсы могут быть описаны в двух форматах:

Форматы ресурсов

1. Файлы .properties

Файлы с расширением .properties - стандартный текстовый формат для хранения пар "ключ-значение".

Пример:

^{МоиРесурсы_ru.properties}

# Многострочное описание
ОписаниеПриложения = Приложение для управления \
                     системными сервисами

# Основные команды
Команда.Старт = Старт
Команда.Стоп = Стоп

^{МоиРесурсы_en.properties}

# Multiline description
ОписаниеПриложения = Application for managing \
                     system services

# Main commands
Команда.Старт = Start
Команда.Стоп = Stop

2. Классы на OneScript (.os)

Классы с расширением .os предоставляют расширенные возможности:

• Использовать любой тип данных (не только строки)
• Динамически генерировать ресурсы
• Интегрировать сложную логику

Пример класса:

^{МоиРесурсы_en.os}

Функция ПолучитьРесурсы() Экспорт
	Ресурсы = Новый Соответствие;

	Ресурсы.Вставить("ОписаниеПриложения", "Application for managing system services");
	Ресурсы.Вставить("Команда.Старт", "Start");
	Ресурсы.Вставить("Команда.Стоп", "Stop");

	Возврат Ресурсы;
КонецФункции

Рекомендуемая организация ресурсов

...
src/
└── locales/
    ├── ru/
    │   └── МоиРесурсы_ru_RU.properties
    ├── en/
    │   └── МоиРесурсы_en_GB.properties
    ├── es/
    │   └── МоиРесурсы_es.properties
    ├── global/
    │   └── МоиРесурсы.properties
    └── ...

Правила наименования файлов ресурсов

Именование файла ресурсов играет важную роль, т.к. по имени файла определяется его базовое имя пакета и локаль.

Формат	Область действия	Примеры
<Базовое имя пакета>.<Расширение>	Все локали	МоиРесурсы.properties
<Базовое имя пакета>_<Код языка>.<Расширение>	Язык (все регионы)	МоиРесурсы_en.os
<Базовое имя пакета>_<Код языка>_<Код страны>.<Расширение>	Конкретный язык и регион	МоиРесурсы_en_US.properties

Механизм поиска файлов ресурсов пакета

Поиск файлов ресурсов происходит в определенном порядке. Рассмотрим на следующем примере:

Текущее окружение:

• Базовое имя пакета: МоиРесурсы
• Текущая локаль: ru_RU</br>
• Локаль по умолчанию: en_US
• Имеющиеся файлы ресурсов: МоиРесурсы_en.os, МоиРесурсы.properties

Сначала загрузчик попытается найти файлы в следующем порядке:

1. Поиск для ru_RU:

• МоиРесурсы_ru_RU.os ❌ не найден
• МоиРесурсы_ru_RU.properties ❌ не найден
• МоиРесурсы_ru.os ❌ не найден
• МоиРесурсы_ru.properties ❌ не найден

1. Поиск базового пакета:

• МоиРесурсы.os ❌ не найден
• МоиРесурсы.properties ✅ найден

На этом этапе загрузчик найдет файл МоиРесурсы.properties, но поиск продолжится, т.к. это базовый пакет.

1. Поиск для локали по умолчанию (en_US):

• МоиРесурсы_en_US.os ❌ не найден
• МоиРесурсы_en_US.properties ❌ не найден
• МоиРесурсы_en.os ✅ найден
• МоиРесурсы_en.properties ❌ не найден

На этом этапе загрузчик найдет файл МоиРесурсы_en.os. На основании найденных файлов будет собран пакет.

Глобальные локали

Статичный класс Мультиязычность предоставляет интерфейс для управления глобальными настройками локалей:

// Управление текущей локалью (по умолчанию: ru_RU)
Мультиязычность.УстановитьЛокаль("es_ES");        // Установка
ТекущаяЛокаль = Мультиязычность.ТекущаяЛокаль();  // Получение

// Управление локалью по умолчанию (по умолчанию: en_US)
Мультиязычность.УстановитьЛокальПоУмолчанию("fr_FR");     // Установка
ЛокальПоУмолчанию = Мультиязычность.ЛокальПоУмолчанию();  // Получение

Встраивание в код приложения

Инициализация

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

_{./src/main.os}

#Использовать i18n

// Указание каталога с ресурсами
ПутьКРесурсам = ОбъединитьПути(ТекущийСценарий().Каталог, "locales");
МенеджерРесурсовЛокализации.ДобавитьКаталог(ПутьКРесурсам);

Работа с пакетами ресурсов

Получение пакетов

// Получение одиночного пакета
Пакет = МенеджерРесурсовЛокализации.ПолучитьПакет("МоиРесурсы");

// Получение группы пакетов
ГруппаПакетов = МенеджерРесурсовЛокализации.ПолучитьПакеты("МоиРесурсы, ОбщиеРесурсы");

Пакеты по умолчанию

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

// Использование пакета по умолчанию
Пакет.ИспользоватьПоУмолчанию();

// Использование группы пакетов по умолчанию
ГруппаПакетов.ИспользоватьПоУмолчанию();

Работа с ресурсами

// Получение ресурса через пакет
ОписаниеПриложения = Пакет.ПолучитьРесурс("ОписаниеПриложения");

// Параметризованная строка
Приветствие = Пакет.ПолучитьСтроку("Приветствие", ИмяПользователя); // Пример шаблона: Hello, %1

// Получение ресурса при использовании пакета по умолчанию
Команда = Мультиязычность.ПолучитьРесурс("Имя.Старт");

// Параметризованная строка при использовании пакета по умолчанию
Статус = Мультиязычность.ПолучитьСтроку("СтатусЗадачи", ИмяЗадачи, Прогресс); // Пример шаблона: Задача %1 выполнена на %2 процентов

Шаблонизация с автоподстановкой

Для использования механизма шаблонизации помечайте места вставки ресурсов специальной конструкцией {t(ИмяРесурса)}

Шаблон = "{
|  'ОписаниеПриложения': '{t(ОписаниеПриложения)}',
|  'Команды': {
|    'Старт': {
|      'Имя': '{t(Имя.Старт)}',
|      'Описание': '{t(Описание.Старт)}'
|    },
|    'Стоп': {
|      'Имя': '{t(Имя.Стоп)}',
|      'Описание': '{t(Описание.Стоп)}'
|    }
|  }
|}";

// Заполнение шаблона 
Результат = Пакет.ЗаполнитьШаблон(Шаблон);

// Заполнение шаблона при использовании пакета по умолчанию
Результат = Мультиязычность.ЗаполнитьШаблон(Шаблон); 

Более подробно написано в описании публичного интерфейса