16.04.2024 07:01
dananaprey 0 605 Источник

Не так давно мне довелось решить интересную задачу, направленную на снижение риска того, что разработчик забудет о мультиязычности приложения и это станет причиной заведения нежеланных багов в будущем. Изначально я искал решение проблемы на Хабре, но, увы, не нашел. Поэтому решил написать на эту тему статью в блоге ЛАНИТ, которая, надеюсь, поможет кому-то в будущем.

Предлагаю вашему вниманию практическое руководство по внедрению статического анализа мультиязычности Angular приложения с помощью ngx-translate-lint (подразумевается, что для локализации Angular приложения уже используется пакет @ngx-translate/core).

Конфигурация

Для начала необходимо установить библиотеку, используя команду:

npm install ngx-translate-lint --save-dev

После установки в корне проекта необходимо создать файл с конфигурацией, например,
ngx-translate-lint.config.json и заполнить его следующим содержанием:

{
  "rules": {
    "keysOnViews": "error",
    "zombieKeys": "error",
    "misprintKeys": "warning",
    "deepSearch": "disable",
    "emptyKeys": "error",
    "maxWarning": "0",
    "misprintCoefficient": "0.9",
    "ignoredKeys": [],
    "ignoredMisprintKeys": [],
    "customRegExpToFindKeys": ["(?<=['])([A-Яа-яёЁ0-9-.,!?() ]+)(?=['])"]
  },
  "project": "./src/app/**/*.{html,ts}",
  "languages": "./src/assets/i18n/*.json"
}

В нём мы можем включать/выключать правила и настраивать степень их важности.
В поле project необходимо указать паттерн для файлов, в которых мы будем искать ключи из файлов локализации.
В поле languages предоставляется путь к файлам локализации.
В поле ignoredKeys можно добавить исключения, которые подходят под регулярное выражение, но их, например, не нужно переводить.
В поле customRegExpToFindKeysнеобходимо указать регулярное выражение, которое будет находить ключи из файлов локализации в проекте.
Подробнее в документации.

В моём случае приложение использует слова и предложения на кириллице в качестве ключей для файлов локализации:

// some-file.component.html
<span>{{ 'Скрыть всё' | translate }}</span>

// some-file.component.ts
this.translateService.instant('Активировать');

Файлы локализации имеют следующий вид:

// en.json
{
  "Скрыть всё": "Hide all",
  "Активировать": "Activate"
}

// ru.json
{
  "Скрыть всё": "Скрыть всё",
  "Активировать": "Активировать"
}

В связи с этим было добавлено регулярное выражение, которое находит слова и предложения на кириллице, включая некоторые знаки препинания и цифры между одинарными кавычками (соглашение):

(?<=['])([А-Яа-яёЁ0-9-.,!?() ]+)(?=['])

Для более традиционного использования файлов локализации, когда ключом является что-то наподобие confirmModalWindow.header, подойдёт регулярное выражение типа:
(?<=['])([a-zA-Z.]+)(?=['])

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

После настройки библиотеки можно добавить новую команду в package.json и запускать её, например, перед коммитом либо добавить в pipeline вашего CI.

"lint:translations": "ngx-translate-lint --config ngx-translate-lint.config.json"

Вывод

Использование данной библиотеки позволит провести статический анализ мультиязычности вашего приложения и поможет избежать следующих ситуаций:

  • Разработчик забыл добавить перевод в файл(-ы) локализации.
    Результат: Ошибка/предупреждение Key: 'Текст, которого нет в одном из файлов локализации' doesn't exist in 'ru.json'

  • Разработчик забыл перевести текст и оставил пустой ключ в файле локализации.
    Результат: Ошибка/предупреждение Key: 'Пустой ключ' is empty in 'en.json'

  • Разработчик удалил старый функционал, но забыл удалить связанные с этим функционалом переводы.
    Результат: Ошибка/предупреждение Key: 'Текст, который не используется в приложении' doesn't exist in project'

  • Разработчик не уверен, что все файлы локализации (допустим, их четыре) имеют все ключи, а проверять вручную долго и сложно.
    Результат: Ошибка/предупреждение Key: 'Текст, которого нет в одном из файлов локализации' doesn't exist in 'ru.json'

  • Разработчик переживает, что потерял какой-либо перевод при решении конфликтов слияния в файлах локализации.

  • Разработчик случайно изменил ключ объекта в файле локализации, что-то из него удалил либо изменил ключ в файлах проекта, и теперь локализация работает некорректно.

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

Как видите, права на ошибку становится меньше, а это значит, что баги, связанные с переводами, будут исправляться на этапе разработки и не доходить до этапа тестирования.

Надеюсь этот материал окажется полезен. Всем чистого и производительного кода!

Комментарии (0)