https://github.com/stivo182/oscript-i18n
Библиотека для локализации приложений на OneScript
https://github.com/stivo182/oscript-i18n
1c i18n internationalization oscript
Last synced: 3 months ago
JSON representation
Библиотека для локализации приложений на OneScript
- Host: GitHub
- URL: https://github.com/stivo182/oscript-i18n
- Owner: Stivo182
- License: mit
- Created: 2025-02-26T20:39:39.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-10-02T15:41:57.000Z (3 months ago)
- Last Synced: 2025-10-02T17:40:17.299Z (3 months ago)
- Topics: 1c, i18n, internationalization, oscript
- Language: 1C Enterprise
- Homepage:
- Size: 75.2 KB
- Stars: 1
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# i18n
Библиотека для локализации приложений на OneScript.
## Установка
``` bash
opm install i18n
```
## Описание
* 1\. [Пакеты ресурсов](#пакеты-ресурсов)
* 1.1\. [Форматы ресурсов](#форматы-ресурсов)
* 1.2\. [Рекомендуемая организация ресурсов](#рекомендуемая-организация-ресурсов)
* 1.3\. [Правила наименования файлов ресурсов](#правила-наименования-файлов-ресурсов)
* 1.4\. [Механизм поиска файлов ресурсов пакета](#механизм-поиска-файлов-ресурсов-пакета)
* 2\. [Глобальные локали](#глобальные-локали)
* 3\. [Встраивание в код приложения](#встраивание-в-код-приложения)
* 3.1\. [Инициализация](#инициализация)
* 3.2\. [Работа с пакетами ресурсов](#работа-с-пакетами-ресурсов)
* 3.3\. [Работа с ресурсами](#работа-с-ресурсами)
* 3.4\. [Шаблонизация с автоподстановкой](#шаблонизация-с-автоподстановкой)
* 4\. [Публичный интерфейс](docs/README.md)
## Пакеты ресурсов
Пакеты ресурсов служат контейнерами для хранения специфичных для локали объектов: переводов текстов, шаблонов сообщений, форматов данных и настроек. Ресурсы могут быть описаны в двух форматах:
### Форматы ресурсов
#### 1. Файлы [.properties](https://ru.wikipedia.org/wiki/.properties)
Файлы с расширением `.properties` - стандартный текстовый формат для хранения пар "ключ-значение".
**Пример:**
МоиРесурсы_ru.properties
``` properties
# Многострочное описание
ОписаниеПриложения = Приложение для управления \
системными сервисами
# Основные команды
Команда.Старт = Старт
Команда.Стоп = Стоп
```
МоиРесурсы_en.properties
``` properties
# Multiline description
ОписаниеПриложения = Application for managing \
system services
# Main commands
Команда.Старт = Start
Команда.Стоп = Stop
```
#### 2. Классы на OneScript (.os)
Классы с расширением `.os` предоставляют расширенные возможности:
- Использовать любой тип данных (не только строки)
- Динамически генерировать ресурсы
- Интегрировать сложную логику
**Пример класса:**
МоиРесурсы_en.os
``` bsl
Функция ПолучитьРесурсы() Экспорт
Ресурсы = Новый Соответствие;
Ресурсы.Вставить("ОписаниеПриложения", "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`
- Локаль по умолчанию: `en_US`
- Имеющиеся файлы ресурсов: _МоиРесурсы_en.os_, _МоиРесурсы.properties_
Сначала загрузчик попытается найти файлы в следующем порядке:
1. Поиск для `ru_RU`:
- МоиРесурсы_ru_RU.os ❌ не найден
- МоиРесурсы_ru_RU.properties ❌ не найден
- МоиРесурсы_ru.os ❌ не найден
- МоиРесурсы_ru.properties ❌ не найден
2. Поиск базового пакета:
- МоиРесурсы.os ❌ не найден
- МоиРесурсы.properties ✅ найден
На этом этапе загрузчик найдет файл _МоиРесурсы.properties_, но поиск продолжится, т.к. это базовый пакет.
3. Поиск для локали по умолчанию (`en_US`):
- МоиРесурсы_en_US.os ❌ не найден
- МоиРесурсы_en_US.properties ❌ не найден
- МоиРесурсы_en.os ✅ найден
- МоиРесурсы_en.properties ❌ не найден
На этом этапе загрузчик найдет файл _МоиРесурсы_en.os_. На основании найденных файлов будет собран пакет.
## Глобальные локали
Статичный класс [Мультиязычность](docs/Мультиязычность.md) предоставляет интерфейс для управления глобальными настройками локалей:
``` bsl
// Управление текущей локалью (по умолчанию: ru_RU)
Мультиязычность.УстановитьЛокаль("es_ES"); // Установка
ТекущаяЛокаль = Мультиязычность.ТекущаяЛокаль(); // Получение
// Управление локалью по умолчанию (по умолчанию: en_US)
Мультиязычность.УстановитьЛокальПоУмолчанию("fr_FR"); // Установка
ЛокальПоУмолчанию = Мультиязычность.ЛокальПоУмолчанию(); // Получение
```
## Встраивание в код приложения
### Инициализация
Перед использованием ресурсов необходимо настроить пути к каталогам с локализованным контентом. Это делается в точке входа приложения:
./src/main.os
``` bsl
#Использовать i18n
// Указание каталога с ресурсами
ПутьКРесурсам = ОбъединитьПути(ТекущийСценарий().Каталог, "locales");
МенеджерРесурсовЛокализации.ДобавитьКаталог(ПутьКРесурсам);
```
### Работа с пакетами ресурсов
#### Получение пакетов
``` bsl
// Получение одиночного пакета
Пакет = МенеджерРесурсовЛокализации.ПолучитьПакет("МоиРесурсы");
// Получение группы пакетов
ГруппаПакетов = МенеджерРесурсовЛокализации.ПолучитьПакеты("МоиРесурсы, ОбщиеРесурсы");
```
#### Пакеты по умолчанию
Для проектов с фиксированным набором пакетов рекомендуется установить их как пакеты по умолчанию.
Это позволит упростить доступ к ресурсам - вместо прямого обращения к менеджеру пакетов использовать единую точку доступа через статичный класс [Мультиязычность](docs/Мультиязычность.md).
``` bsl
// Использование пакета по умолчанию
Пакет.ИспользоватьПоУмолчанию();
// Использование группы пакетов по умолчанию
ГруппаПакетов.ИспользоватьПоУмолчанию();
```
### Работа с ресурсами
``` bsl
// Получение ресурса через пакет
ОписаниеПриложения = Пакет.ПолучитьРесурс("ОписаниеПриложения");
// Параметризованная строка
Приветствие = Пакет.ПолучитьСтроку("Приветствие", ИмяПользователя); // Пример шаблона: Hello, %1
// Получение ресурса при использовании пакета по умолчанию
Команда = Мультиязычность.ПолучитьРесурс("Имя.Старт");
// Параметризованная строка при использовании пакета по умолчанию
Статус = Мультиязычность.ПолучитьСтроку("СтатусЗадачи", ИмяЗадачи, Прогресс); // Пример шаблона: Задача %1 выполнена на %2 процентов
```
### Шаблонизация с автоподстановкой
Для использования механизма шаблонизации помечайте места вставки ресурсов специальной конструкцией `{t(ИмяРесурса)}`
``` bsl
Шаблон = "{
| 'ОписаниеПриложения': '{t(ОписаниеПриложения)}',
| 'Команды': {
| 'Старт': {
| 'Имя': '{t(Имя.Старт)}',
| 'Описание': '{t(Описание.Старт)}'
| },
| 'Стоп': {
| 'Имя': '{t(Имя.Стоп)}',
| 'Описание': '{t(Описание.Стоп)}'
| }
| }
|}";
// Заполнение шаблона
Результат = Пакет.ЗаполнитьШаблон(Шаблон);
// Заполнение шаблона при использовании пакета по умолчанию
Результат = Мультиязычность.ЗаполнитьШаблон(Шаблон);
```
Более подробно написано в описании [публичного интерфейса](docs/README.md)