# Локализация

## Описание работы

Локализация / интернационализация строковых ресурсов во Flutter состоит из двух этапов:
    1. Создание сборника переводов для каждого языка в файлах формата `.arb` (Application Resource Bundle).
    2. Генерация кода на основе сборника переводов.
    3. Использование в приложении / пакете.

### Сборник переводов

Для работы с файлами переводов рекомендуется установить [официальный экстеншн]((https://marketplace.visualstudio.com/items?itemName=Google.arb-editor)) для vscode или другого редактора, т.к. формат стандартизирован и расширения предоставляют проверку пропертей, подсветку и т.д.

На момент написания, основным файлом является `dgis_en.arb`. Это установлено в файле `l10n.yaml`, который находится в корневой директории пакета, рядом с `pubspec.yaml`

Основной файл:
1. Содержит метадату (описание пропертей в форматируемых строках, форматы множеств и тд)
2. Является источником истины о количестве строк и их идентификаторов: если строка есть в `en` и отсутствует в других – будет ошибка при генерации, но не наоборот.
3. Является фоллбэком – если отсутствует перевод в других файлах, будет взята строка отсюда. **Но не наоборот**

#### Метадата

Метадата в переводах – это подстановки в строки, формы множественных чисел и тд. Метадата для строки содержит `@` в ключе перед именем строки.

Должна содержаться только в шаблонном (основном) файле `.arb`. Для других локалей метадата подтянется из этого файла.

### Генерация кода

На основе сборников переводов, генерируются классы для использования в коде. Путь до сгенерированного кода, названия классов и т.д. устанавливаются в файле `plugins/dgis_mobile_sdk/l10n.yaml`.

Команда для генерации кода:

```console
flutter gen-l10n
```

Сгенерированные классы будут в `lib/l10n/generated`.

## Пример использования

В `MaterialApp` необходимо добавить делегат сгенерированного класса:

```dart
    return MaterialApp(
      localizationsDelegates: const [DgisLocalizations.delegate],
    );
```

В коде виджетов получить строки можно через

```dart
final localizations = DgisLocalizations.of(context)!; // в localizations будут доступны все строки, будет работать автокомплит и тд.
```

## Полезные ссылки

- [Официальная дока по локализации](https://docs.flutter.dev/ui/accessibility-and-internationalization/internationalization)
- [Формат файлов .arb (Application Resource Bundle)](https://github.com/google/app-resource-bundle)
- [Extension VS code для работы с .arb файлами](https://marketplace.visualstudio.com/items?itemName=Google.arb-editor)