Рабочие процессы локализации в CI/CD

Lingo.dev берёт локализацию на себя прямо в CI/CD. Есть два пути: GitHub App, который реагирует на пуши и pull request'ы на стороне сервера, или CLI в вашем собственном пайплайне. Оба синхронизируют переводы при каждом изменении и обрабатывают только те строки, которые реально изменились, — так локализация остаётся быстрой и экономичной по мере роста проекта.

Вариант 1: GitHub App (рекомендуется)#

GitHub App — самый простой способ запустить непрерывную локализацию. Он следит за репозиторием и переводит на стороне сервера: ничего не нужно устанавливать в пайплайн и хранить API-ключ как CI-секрет.

Настройка — разовая:

1. Установите Lingo.dev GitHub App на свой репозиторий.
2. Зафиксируйте .lingo/config.json с orgId, engineId, исходной локалью, целевыми локалями и файлами для перевода. Запустите lingo init и lingo link локально, чтобы сгенерировать его, затем зафиксируйте результат.
3. Сделайте пуш.

Дальше App сам управляет обоими сценариями рабочего процесса:

• При пуше в ветку по умолчанию переводы коммитятся обратно в неё.
• При создании pull request'а переводы добавляются в него — вы сможете проверить их перед слиянием.

App отслеживает состояние переводов на стороне сервера, поэтому в репозитории нет lockfile, способного вызвать конфликты, и настраивать шаг верификации не нужно — целевые локали просто остаются в sync с исходной.

Вариант 2: CLI в своём пайплайне#

Если вы не на GitHub или хотите запускать локализацию как явный шаг рядом со сборкой и тестами — используйте CLI напрямую. Он работает в любой CI-среде с Node.js 22 и новее: GitHub Actions, GitLab CI, Bitbucket Pipelines и не только.

Схема всегда одна:

1. Установите @lingo.dev/cli.
2. Аутентифицируйтесь с помощью API-ключа через переменную окружения LINGO_API_KEY.
3. Запустите lingo push, чтобы перевести изменённые строки.
4. Зафиксируйте результаты или откройте pull request из задания.

Сохраните API-ключ Lingo.dev как CI-секрет и передайте его через LINGO_API_KEY. Зафиксированный .lingo/config.json указывает CLI, что переводить, а зафиксированный .lingo/lock.json (обновляемый командой lingo push) отслеживает состояние — обрабатываются только изменённые строки.

Минимальный пример для GitHub Actions#

Этот рабочий процесс устанавливает CLI, переводит при каждом пуше в main и коммитит результаты обратно:

name: Localize
on:
  push:
    branches: [main]
permissions:
  contents: write
jobs:
  localize:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm install -g @lingo.dev/cli
      - run: lingo push
        env:
          LINGO_API_KEY: ${{ secrets.LINGO_API_KEY }}
      - name: Commit translations
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add .
          git commit -m "chore: update translations" || echo "No changes"
          git push

Те же две строки — npm install -g @lingo.dev/cli, затем lingo push — вставляются в блок script: GitLab CI или в шаг Bitbucket Pipelines. Задайте LINGO_API_KEY как маскированную или защищённую переменную CI на этих платформах.

Коммит или pull request?#

Какой бы путь вы ни выбрали, вы сами решаете, как применять переводы:

GitHub App даёт оба варианта автоматически — коммитит при пушах в ветку по умолчанию и добавляет переводы в открытые PR. В своём пайплайне выбор за вами: фиксируйте результаты, как показано выше, или открывайте pull request вместо пуша в ветку.

Проверка переводов перед деплоем#

Чтобы непереведённый контент не попал в продакшн, добавьте lingo check как шлюз перед шагом деплоя. Команда завершается с ненулевым кодом, если какие-то строки ещё не переведены:

- name: Verify translations
  run: lingo check

GitHub App непрерывно синхронизирует локали, поэтому отдельный шаг верификации актуален в основном при самостоятельном запуске CLI.

Монорепозитории#

Если в монорепозитории у каждого пакета есть свой .lingo/config.json, ограничьте запуск конкретным пакетом с помощью glob или запустите CLI из директории этого пакета:

lingo push "apps/web/**"

Что дальше#