GitLab CI/CD

Запустите Lingo.dev в GitLab CI, чтобы каждый merge request, где добавляются или меняются исходные строки, возвращался с уже готовыми переводами. Пайплайн запускает lingo push, движок переводит только новые или изменённые ключи, а результат коммитится прямо в ветку MR — переводы появляются в diff merge request и проходят проверку до того, как человек выполнит слияние. В ветку по умолчанию ничего не попадает незамеченным.

Что понадобится#

• Организация и движок Lingo.dev, а также сервисный API-ключ (Dashboard → API Keys → create, type service).

• Проект, настроенный для Lingo.dev. Один раз сгенерируйте его командой:

  bashCopy

  npx @lingo.dev/cli@latest init   # scaffolds .lingo/config.json
  npx @lingo.dev/cli@latest link   # connects the project to your org + engine

  .lingo/config.json задаёт исходную и целевые локали, а также globs исходных файлов:

  jsonCopy

  {
    "sourceLocale": "en",
    "targetLocales": ["es", "fr", "de", "zh"],
    "files": [{ "pattern": "locales/en.json" }],
    "orgId": "org_...",
    "engineId": "eng_..."
  }

• Закоммиченная базовая версия. При первом запуске переведите всё и закоммитьте результат, чтобы у CI был lockfile для сравнения:

  bashCopy

  npx @lingo.dev/cli@latest push --backfill-missing --wait
  git add locales .lingo && git commit -m "chore(i18n): baseline translations"

Токены доступа#

Добавьте две masked переменные CI/CD в разделе Settings → CI/CD → Variables:

• LINGO_API_KEY — ваш сервисный ключ Lingo.dev (lingo_sk_...). CLI автоматически использует его для аутентификации.
• GITLAB_PUSH_TOKEN — Project Access Token с областью действия write_repository (роль Developer). Он позволяет CI коммитить переводы обратно в ветку MR.

Пайплайн#

Закоммитьте этот .gitlab-ci.yml. Он запускается для merge request в ветку по умолчанию и отправляет переводы обратно в исходную ветку MR:

stages:
  - localize

localize:
  stage: localize
  image: node:22-alpine
  rules:
    # Only on merge requests that target the default branch.
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == $CI_DEFAULT_BRANCH'
  before_script:
    - apk add --no-cache git
  script:
    # Pin the CLI version — never @latest; bump deliberately after testing.
    # --wait blocks until the engine finishes and writes files: since 1.6.0
    # `push` is async by default (it submits the run and exits), so CI must
    # wait to have something to commit.
    - npx -y @lingo.dev/cli@1.6.0 push --wait
    - |
      if [ -z "$(git status --porcelain)" ]; then
        echo "Translations already up to date — nothing to commit."
        exit 0
      fi
      git config user.name "lingo-bot"
      git config user.email "bot@lingo.dev"
      git add locales .lingo/lock.json
      # [skip ci] keeps the bot's own commit from re-triggering this pipeline.
      git commit -m "chore(i18n): sync translations [skip ci]"
      git push "https://oauth2:${GITLAB_PUSH_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git" "HEAD:${CI_MERGE_REQUEST_SOURCE_BRANCH_NAME}"

Попробуйте#

git checkout -b feat/new-strings
# add or change a key in locales/en.json
git commit -am "feat: add strings" && git push -u origin feat/new-strings
# open an MR feat/new-strings -> main (UI, or: glab mr create --fill --target-branch main)

Пайплайн MR запускает lingo push --wait, коммитит locales/{...}.json вместе с обновлённым .lingo/lock.json в ветку MR, и переводы появляются в diff. Затем проверяющий при необходимости правит значения и выполняет слияние.

Как сохраняются правки человека#

lingo push сохраняет ручные правки на уровне ключей:

• Измените целевую строку, не меняя её английский исходник → эта строка сохранится, а все остальные ключи продолжат переводиться.
• Изменился английский исходник у уже отредактированного ключа → для этого ключа будет сгенерирован новый перевод (потому что изменился смысл).
• Добавлен новый исходный ключ → он будет переведён и добавлен даже в файлы, где есть ручные правки.

Иными словами, правка проверяющего в MR переживёт все последующие запуски пайплайна, а новые и изменённые ключи будут автоматически добавляться.

Режимы push#

• lingo push — инкрементальный режим; вариант по умолчанию для CI. Переводит только новые и изменённые ключи, сохраняя всё остальное. Добавьте --wait в CI, чтобы процесс ждал записи результатов (в 1.6.0+ по умолчанию используется асинхронный режим).
• lingo push --backfill-missing — первый push / начальная настройка новой локали; заполняет целевые файлы, которых ещё нет. Не подходит для постоянных изменений.
• lingo push --force --yes — заново переводит всё с нуля (перезаписывает ручные правки). Используется редко.

Кастомизация#

• Автокоммит в ветку по умолчанию вместо MR: запускайте по $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH и отправляйте обратно в $CI_DEFAULT_BRANCH. Так проще, но AI-результат попадает в ветку по умолчанию без проверки.
• Закрепите конкретные строки: используйте preservedKeys / lockedKeys в .lingo/config.json, чтобы выбранные ключи оставались фиксированными, даже если их исходник изменится.
• Self-hosted GitLab: работает без изменений. На gitlab.com новые аккаунты должны пройти проверку личности, прежде чем shared runners смогут запускать CI-задачи.

Что дальше#