Интеграция с Crowdin, Lokalise, Phrase

Современные проекты на JavaScript редко ограничиваются ручным ведением JSON-файлов локализации. При росте количества языков и строк интерфейса возникает необходимость централизованного управления переводами, контроля версий и синхронизации с продуктовой разработкой. В экосистеме i18next это решается через интеграцию с платформами управления локализацией и автоматизированные пайплайны выгрузки/загрузки ресурсов.

Архитектурно i18next отделяет слой получения переводов от их хранения. Ключевая роль отводится backend-плагинам и процессам синхронизации, которые позволяют подключать внешние сервисы без изменения логики приложения.

Принципы работы с внешними TMS в контексте i18next

Интеграция с системами управления переводами (Translation Management System, TMS) строится на нескольких базовых принципах:

  • Source of truth: исходные ключи переводов хранятся либо в репозитории, либо в TMS
  • Синхронизация форматов: JSON, YAML, CSV или специализированные форматы платформ
  • Разделение ответственности: разработка управляет ключами, локализация — переводами
  • Автоматизация обмена: CLI-инструменты и API обеспечивают непрерывную синхронизацию

В связке с i18next чаще всего используется стратегия, при которой приложение загружает переводы динамически, а TMS выступает центральным хранилищем и интерфейсом для переводчиков.

Интеграция с Crowdin

Crowdin предоставляет API и CLI-инструменты, ориентированные на автоматическую синхронизацию файлов локализации.

Структура проекта

Типичная структура для i18next:

locales/
  en/translation.json
  ru/translation.json
  de/translation.json

В Crowdin проекте аналогичная структура отображается через конфигурационный файл crowdin.yml:

project_id: your_project_id
api_token: your_api_token

files:
  - source: /locales/en/translation.json
    translation: /locales/%two_letters_code%/translation.json

Синхронизация

Загрузка исходных файлов в систему:

crowdin upload sources

Скачивание переводов:

crowdin download

Интеграция с i18next

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

import i18n from 'i18next';
import HttpBackend from 'i18next-http-backend';

i18n
  .use(HttpBackend)
  .init({
    lng: 'ru',
    fallbackLng: 'en',
    backend: {
      loadPath: '/locales/{{lng}}/{{ns}}.json'
    }
  });

Основная идея заключается в том, что Crowdin отвечает за актуальность файлов, а i18next — за их потребление в runtime.

Интеграция с Lokalise

Lokalise ориентируется на API-first подход и активно используется в продуктовых командах, работающих с частыми релизами.

API-ориентированная синхронизация

Основной сценарий — загрузка ключей через CLI или API:

lokalise2 file upload \
  --project-id PROJECT_ID \
  --token API_TOKEN \
  --file "locales/en/translation.json" \
  --lang-iso en

Загрузка переводов:

lokalise2 file download \
  --project-id PROJECT_ID \
  --token API_TOKEN \
  --format json \
  --directory-prefix locales

Формат ключей i18next

Lokalise поддерживает вложенные ключи, что совпадает с подходом i18next:

{
  "auth": {
    "login": "Войти",
    "logout": "Выйти"
  }
}

В i18next это автоматически резолвится через namespace:

i18n.t('auth.login');

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

Lokalise позволяет использовать ветки (branches), что удобно для синхронизации с Git-flow:

  • master — продакшн переводы
  • develop — активная разработка
  • feature-ветки — экспериментальные строки

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

Интеграция с Phrase

Phrase отличается глубокой интеграцией с CI/CD и поддержкой сложных workflow для enterprise-сценариев.

CLI-синхронизация

Установка и базовые команды:

phrase push
phrase pull

Конфигурация через phrase.yml:

phrase:
  project_id: YOUR_PROJECT_ID
  file_format: json
  push:
    sources:
      - file: ./locales/en/translation.json
  pull:
    targets:
      - file: ./locales/%locale_name%/translation.json

Автоматизация в CI

Phrase часто интегрируется в pipeline:

steps:
  - name: Upload sources
    run: phrase push

  - name: Download translations
    run: phrase pull

Работа с namespaces i18next

Phrase хорошо сочетается с архитектурой namespaces:

locales/
  en/
    common.json
    auth.json
    dashboard.json

i18next конфиг:

i18n.init({
  ns: ['common', 'auth', 'dashboard'],
  defaultNS: 'common',
  backend: {
    loadPath: '/locales/{{lng}}/{{ns}}.json'
  }
});

Синхронизация ключей и предотвращение рассинхронизации

Во всех трёх системах критической задачей является предотвращение рассинхронизации ключей между кодом и TMS.

Распространённые стратегии:

  • Extraction из кода: использование i18next-parser для генерации JSON
  • Locking ключей: запрет удаления ключей без ревью
  • Pseudo-localization: тестирование интерфейса с искусственными строками
  • CI-валидация: проверка отсутствующих ключей

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

i18next "src/**/*.{js,jsx,ts,tsx}" \
  --config i18next-parser.config.js

Конфигурация i18next для работы с внешними переводами

Независимо от выбранной TMS, конфигурация i18next остаётся унифицированной:

i18n.init({
  lng: 'en',
  fallbackLng: 'en',
  ns: ['common'],
  defaultNS: 'common',
  backend: {
    loadPath: '/locales/{{lng}}/{{ns}}.json'
  },
  interpolation: {
    escapeValue: false
  },
  saveMissing: false
});

При использовании TMS ключевым становится не runtime-слой, а процесс доставки файлов в loadPath.

Версионирование переводов

Интеграция с Crowdin, Lokalise и Phrase обычно дополняется версионированием:

  • hash-коммит перевода
  • привязка к релизу
  • хранение snapshot’ов локализации

Практический подход:

/locales/v1/en/translation.json
/locales/v2/en/translation.json

или через query version:

loadPath: '/locales/{{lng}}/{{ns}}.json?v=42'

Инкрементальные обновления переводов

При больших проектах полная синхронизация становится неэффективной. Используются инкрементальные обновления:

  • загрузка только изменённых ключей
  • delta API TMS
  • webhook-уведомления о новых переводах

Phrase и Lokalise предоставляют webhook-и, позволяющие автоматически триггерить сборку фронтенда после обновления переводов.

Безопасность и контроль доступа

TMS-интеграции требуют строгого контроля:

  • API-токены с ограниченными правами
  • разделение окружений (dev/staging/prod)
  • аудит изменений переводов
  • роль-based доступ для переводчиков

Crowdin реализует granular permissions, позволяя разделять доступ к языкам и проектам.

Оптимизация загрузки переводов в i18next

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

  • lazy-loading namespaces
  • CDN для JSON-файлов
  • кеширование backend-загрузчика
  • компрессия переводов

Пример кеширования:

backend: {
  loadPath: '/locales/{{lng}}/{{ns}}.json',
  requestOptions: {
    cache: 'force-cache'
  }
}

Для крупных приложений это снижает нагрузку на TMS и ускоряет первый рендер интерфейса.

Оглавление