Пример настройки GitLab CI

Переводите файлы в доверенном пайплайне GitLab, отправляйте результат через запрос на слияние и блокируйте запросы с устаревшими переводами.

Раннер GitLab может переводить файлы репозитория с помощью CLI Lingo.dev и сохранять результаты как артефакты задания. Так для перевода используются те же checkout, проверки и процесс выпуска, что и для остального приложения. GitLab отвечает за выполнение пайплайна и отправку результатов в репозиторий, а Lingo.dev обрабатывает выбранные исходные файлы с помощью движка локализации.

Это пример настройки CI, а не встроенное подключение учётной записи GitLab. Начните с ручного запуска пайплайна в ветке по умолчанию. Проверьте результат, а затем добавьте регулярные запуски и отправку результатов через запросы на слияние.

Подготовьте исходные файлы и учётные данные #

Пройдите краткое руководство по CLI на своём компьютере. Добавьте в коммит .lingo/config.json, принятые файлы перевода и .lingo/lock.json. Конфигурация задаёт исходную локаль, целевые локали, шаблоны файлов и движок локализации. Запускайте CLI из каталога с этой конфигурацией.

Создайте недостающие файлы перевода с помощью lingo push --backfill-missing --wait. Для последующих изменений исходных файлов используйте обычный lingo push --wait. Изменение инструкций движка локализации само по себе не перезаписывает принятые файлы. Если нужно сгенерировать их заново, сделайте это отдельно.

В настройках переменных CI/CD проекта сохраните LINGO_API_KEY как маскируемую переменную. CLI читает только это имя и игнорирует переменную LINGODOTDEV_API_KEY из предыдущей версии CLI, поэтому переименуйте её. Разрешите доступ к ней только доверенным веткам или окружениям, из которых можно отправлять задания на перевод. Защищённая переменная может быть недоступна в незащищённой ветке или запросе на слияние. Используйте ветку с разрешённым доступом, а не открывайте переменную недоверенному коду.

Ключ API даёт право выполнять перевод. Учётные данные GitLab с правом записи в репозиторий понадобятся только при настройке отправки результатов через коммиты.

В примерах зафиксирована версия CLI 1.21.0. Команда lingo check проверяет файлы переводов начиная с CLI 1.20.0. Чтобы управлять версией через зависимости проекта и Lockfile, следуйте руководству по настройке CI.

Запустите пайплайн, который сначала сохраняет артефакты #

В этом примере .gitlab-ci.yml предполагается, что locales/en.json — настроенный исходный файл, а locales/es.json — существующий файл на испанском и единственный целевой файл. Если целевых файлов больше, выполните test -s и проверки JSON для каждого из них. В остальных командах, где указан locales/es.json, перечислите пути ко всем целевым файлам. Lockfile отмечает исходный файл как переведённый, поэтому при следующем push он будет пропущен. При этом целевой файл, не попавший в артефакт или коммит, останется устаревшим. В примере используется пайплайн, запущенный вручную в ветке по умолчанию:

yaml
stages:
  - translate

translate_catalog:
  stage: translate
  image: node:22
  rules:
    - if: '$CI_PIPELINE_SOURCE == "web" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
  script:
    # Replace 1.21.0 with the current CLI version.
    - npx -y @lingo.dev/cli@1.21.0 push --wait
    - test -s locales/es.json
    - node -e 'JSON.parse(require("node:fs").readFileSync("locales/es.json", "utf8"))'
    - git diff -- locales/es.json .lingo/lock.json
  artifacts:
    paths:
      - locales/es.json
      - .lingo/lock.json

С --wait задание ждёт завершения запуска и записывает переведённые файлы в checkout. Без этого lingo push лишь отправляет задание на запуск и завершает работу. Поэтому на следующих шагах не будет новых файлов для проверки или коммита.

Проверьте, что раннеру доступен реестр, и подготовьте инструменты для следующих шагов. Например, в другом минимальном образе может потребоваться установить Git, чтобы просматривать изменения или добавлять их в коммит.

Проверьте ИД организации и движка в сохранённом в коммите .lingo/config.json. Внесите одно изменение в исходный файл и запустите пайплайн. Проверьте в логе состояние запуска и изменённую запись в файле перевода. Скачайте артефакт, сравните перевод с этой версией исходного файла и загрузите его в приложение. Проверки наличия файла и корректности JSON сами по себе не подтверждают актуальность перевода и точность его смысла.

--wait скачивает готовый результат, но при включённой ручной проверке задание может остаться в ожидании проверки человеком. Прежде чем добавлять ожидание проверки или отдельное задание для получения результатов, настройте сохранение состояния запуска CI. После отправки экспортируйте указатель именно этого запуска и исходный абсолютный путь к корню проекта. Включите .lingo-ci/run.json, .lingo-ci/project-root.txt, .lingo/config.json, locales/en.json, файл перевода и Lockfile в артефакты задания с ограниченным доступом. Задайте when: always в конфигурации artifacts и выберите срок хранения, достаточный для проверки. Убедитесь, что экспорт выполняется и при сбое последующих проверок. Не скрывайте исходную ошибку.

Завершите проверку, затем на раннере для получения результатов восстановите сохранённую версию и состояние файлов по тому же абсолютному пути к корню проекта. Восстановите только указатель этого запуска, отдельно пройдите аутентификацию и используйте lingo pull --dry-run перед сбором результатов. Если раннер не может воссоздать исходный путь, используйте для обоих заданий постоянный раннер с нужными правами. Никогда не архивируйте всё содержимое ~/.lingo. Успешная отправка задания или наличие старого файла перевода сами по себе не дают новых файлов для публикации.

Добавьте переводы коммитом в запрос на слияние #

Это задание переводит изменения исходных файлов в запросе на слияние и добавляет результаты коммитом в ту же ветку. Предполагается, что первоначальное заполнение переводов уже сохранено в коммите, а в движке отключена Ручная проверка. Так перевод может завершиться за одно задание.

В GitLab 18.4 или новее откройте Настройки, в разделе CI/CD найдите Разрешения токена задания и включите Разрешить Git push в репозиторий. Задание использует встроенный токен GitLab. У человека, который его запускает, должно быть право отправлять изменения в исходную ветку. См. настройку токена задания в GitLab.

Сохраняйте LINGO_API_KEY маскируемой и защищённой переменной. Используйте доверенные исходную и целевую ветки в одном проекте, защитите обе ветки и включите Разрешить пайплайнам запросов на слияние доступ к защищённым переменным и раннерам в настройках CI/CD проекта. Человеку, который запускает пайплайн, также нужно право отправлять или сливать изменения в целевую ветку. Это требования GitLab к защищённым переменным.

Используйте те же пути к исходному файлу и файлу перевода, что и в первом примере. Добавьте это задание на этап translate:

yaml
translate_merge_request:
  stage: translate
  image: node:22
  resource_group: lingo-mr-$CI_MERGE_REQUEST_IID
  rules:
    - if: >-
        $CI_PIPELINE_SOURCE == "merge_request_event" &&
        $CI_MERGE_REQUEST_EVENT_TYPE == "detached" &&
        $CI_MERGE_REQUEST_SOURCE_PROJECT_ID == $CI_MERGE_REQUEST_TARGET_PROJECT_ID
  script:
    # Replace 1.21.0 with the current CLI version.
    - npx -y @lingo.dev/cli@1.21.0 push --wait
    - test -s locales/es.json
    - node -e 'JSON.parse(require("node:fs").readFileSync("locales/es.json", "utf8"))'
    - git add -- locales/es.json .lingo/lock.json
    - if git diff --cached --quiet; then exit 0; fi
    - git config user.name "Localization bot"
    - git config user.email "localization@example.com"
    - git commit -m "Update translations"
    - git push "$CI_REPOSITORY_URL" "HEAD:refs/heads/$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME"

resource_group запускает не более одного задания перевода одновременно для каждого MR. Задание добавляет в коммит только файл перевода на испанский и Lockfile перевода. Если ветка изменится во время перевода, Git отклонит push. Запустите пайплайн для обновлённой ветки.

CI_REPOSITORY_URL предоставляет учётные данные токена задания. Отправка изменений с этим токеном не запускает новый пайплайн, поэтому добавьте проверки ресурсов приложения перед шагом создания коммита. Проверьте изменения перевода в MR и выполните оставшиеся проверки перед слиянием.

Этот push не запускает пайплайн, поэтому у последнего коммита запроса на слияние пайплайна нет. Если в проекте включено требование Пайплайны должны завершаться успешно, GitLab может заблокировать слияние. В таком случае выберите Запустить пайплайн на вкладке Пайплайны запроса на слияние. Задание не найдёт изменений для отправки и завершится без коммита, а пайплайн присвоит статус последнему коммиту.

Создание запроса на слияние с переводами из ветки по умолчанию #

Это задание переводит каждое изменение, попавшее в ветку по умолчанию, и создаёт запрос на слияние с результатом. Параметры push в GitLab создают запрос на слияние в рамках того же git push — без вызова API и дополнительных инструментов. Здесь действуют те же условия, что и для задания выше: первоначальный перевод уже добавлен в коммит, а Ручная проверка отключена.

Создайте токен доступа к проекту с ролью «Разработчик» и областью доступа write_repository. Сохраните его как маскируемую защищённую переменную CI/CD с именем GITLAB_PUSH_TOKEN. На GitLab.com токены доступа к проекту доступны только на платных тарифах. Здесь CI_JOB_TOKEN не используется, потому что GitLab не запускает пайплайн при push с этим токеном. В URL для push используется CI_SERVER_FQDN — это сохраняет порт экземпляра на собственном сервере, если он отличается от стандартного. Для CI_SERVER_FQDN требуется GitLab 16.10 или новее. На более старом экземпляре на собственном сервере используйте ${CI_SERVER_HOST}:${CI_SERVER_PORT}.

Добавьте это задание на этап translate:

yaml
translate_default_branch:
  stage: translate
  image: node:22
  resource_group: lingo-translations
  rules:
    - if: '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
  script:
    - git fetch --quiet "$CI_REPOSITORY_URL" "$CI_DEFAULT_BRANCH"
    - if [ "$(git rev-parse FETCH_HEAD)" != "$CI_COMMIT_SHA" ]; then exit 0; fi
    # Replace 1.21.0 with the current CLI version.
    - npx -y @lingo.dev/cli@1.21.0 push --wait
    - test -s locales/es.json
    - node -e 'JSON.parse(require("node:fs").readFileSync("locales/es.json", "utf8"))'
    - git add -- locales/es.json .lingo/lock.json
    - if git diff --cached --quiet; then exit 0; fi
    - git config user.name "Localization bot"
    - git config user.email "localization@example.com"
    - git commit -m "Update translations"
    - >-
      git push --force
      -o ci.skip
      -o merge_request.create
      -o merge_request.target="$CI_DEFAULT_BRANCH"
      -o merge_request.title="Update translations"
      "https://oauth2:${GITLAB_PUSH_TOKEN}@${CI_SERVER_FQDN}/${CI_PROJECT_PATH}.git"
      "HEAD:refs/heads/lingo/translations"

lingo push --wait завершается с ненулевым кодом, если хотя бы один целевой файл не проходит проверку. Поэтому задание останавливается до коммита. Если изменений нет, команда выводит «Nothing to push», подготовленных к коммиту изменений нет, и задание завершается без коммита.

Первые две строки останавливают задание, если в ветке по умолчанию уже появились коммиты новее того, на котором оно запущено. resource_group выполняет по одному заданию, но в стандартном для GitLab режиме обработки unordered ожидающие задания запускаются без определённого порядка. Без этой проверки старое задание могло бы выполниться последним и принудительно перезаписать новые переводы старыми. Задание для последнего коммита переводит его изменения, а изменения уже устаревшего коммита на перевод не отправляются.

Задание не зацикливается. Оно запускается только при push в ветку по умолчанию и записывает изменения только в lingo/translations. Согласно документации GitLab, -o ci.skip влияет только на пайплайны веток, но не на пайплайны запросов на слияние. Пайплайн запроса на слияние запускается при создании запроса или появлении нового коммита в его исходной ветке. Поэтому проверка ниже должна запускаться для запроса на слияние с переводами. Убедитесь в этом при первом запуске. Слияние этого запроса запустит задание ещё раз, но оно не найдёт изменений для отправки.

При каждом запуске задание заново создаёт lingo/translations на основе коммита ветки по умолчанию, на котором оно запущено, и отправляет результат принудительным push. Поэтому открытый запрос на слияние показывает актуальные изменения переводов. Следующий запуск перезапишет ручные правки в этой ветке — вносите их после слияния. Пока запрос не слит, в ветке по умолчанию остаётся прежний .lingo/lock.json, поэтому следующий запуск снова отправляет на перевод те же изменения исходных файлов. Если последующие коммиты отменят все изменения исходных файлов, переведённые в этом запросе, следующий запуск не найдёт изменений для отправки. Запрос останется открытым с устаревшими переводами — закройте его, а не выполняйте слияние.

Блокировка запросов на слияние с устаревшими переводами #

Команда lingo check сравнивает каждый настроенный исходный файл с .lingo/lock.json и требует наличия всех целевых файлов. Она завершается с кодом 1, если исходный файл изменился после последнего перевода, в Lockfile нет записи о нём, отсутствует целевой файл или ни один исходный файл не соответствует шаблонам files. Команде не нужны ключ API или переменная CI/CD. Она ничего не записывает, поэтому работает и в запросах на слияние из форков. Кроме телеметрии CLI, которую отключает DO_NOT_TRACK=1, команда не делает сетевых запросов. При этом в примерах npx CLI всё равно скачивается из npm перед проверкой. Команда заменяет проверку --frozen из предыдущей версии CLI.

Команда проверяет файлы, а не ключи: целевой файл с ручными правками проходит проверку, а отсутствие ключа в существующем целевом файле не отмечается. Исключение — каталоги React .jsonc. Без .lingo/lock.json команда не видит изменений исходных файлов. Поэтому изменённый или ещё ни разу не отправленный через push исходный файл не вызывает ошибку проверки, о чём команда сообщает в stderr. Добавьте в коммит Lockfile, который записывает lingo push.

Добавьте check в список stages, затем добавьте задание для вашей конфигурации. Если разработчики запускают lingo push --wait и добавляют результат в коммит вместе с изменением исходного файла, проверяйте каждый запрос на слияние:

yaml
check_translations:
  stage: check
  image: node:22
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
  script:
    # lingo check needs CLI 1.20.0 or newer.
    - npx -y @lingo.dev/cli@1.21.0 check

Если вы используете задание для ветки по умолчанию, проверяйте только созданный им запрос на слияние с переводами. Запросы на слияние с новыми функциями меняют исходные файлы ещё до перевода:

yaml
check_translations:
  stage: check
  image: node:22
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME == "lingo/translations"'
  script:
    # lingo check needs CLI 1.20.0 or newer.
    - npx -y @lingo.dev/cli@1.21.0 check

Эта проверка подходит для конфигурации, в которой переводы добавляются в коммит вместе с изменением исходного файла:

Где выполняется переводПроверка каждого запроса на слияние
Разработчики запускают lingo push --wait и добавляют результат в коммит до создания запроса на слияниеДа. Проверка блокирует запрос на слияние, если исходный файл изменился без перевода.
Задание для запроса на слияние добавляет коммит в исходную веткуНет. Проверка выполнялась бы для коммита до перевода, а push из задания не запускает новый пайплайн.
Задание для ветки по умолчанию создаёт запрос на слияние с переводамиТолько для lingo/translations, со вторым заданием выше. В этой схеме запросы на слияние с новыми функциями меняют исходные файлы до перевода.

Хеши исходных файлов учитывают каждый байт. Убедитесь, что checkout, в котором выполнялся lingo push, и checkout в CI используют одинаковые окончания строк. Например, настройте это с помощью * text=auto eol=lf в .gitattributes.

Сделайте регулярные запуски предсказуемыми #

Ограничьте автоматические задания нужными доверенными ветками и путями к исходным файлам. Если используете триггеры запросов на слияние, также ограничьте исходный проект и целевую ветку. Чтобы автоматически созданные коммиты не отправляли задания на перевод снова и снова, настройте подходящее правило для ветки или политику пропуска CI, а также выход при отсутствии изменений.

В монорепозитории перейдите в пакет с нужной конфигурацией и сохраняйте результаты и состояние по путям относительно этого пакета. У независимых пакетов могут быть разные движки локализации и локали. Храните их Lockfile отдельно. Тот же подход с раннером работает и в GitLab на собственной инфраструктуре, если это позволяют сетевой доступ, инструменты раннера, переменные и политика репозитория.

Обычный инкрементальный перевод может сохранить вручную отредактированный ключ перевода, пока исходный текст не меняется. Если исходный текст изменится, этот ключ может быть сгенерирован заново. Заполнение недостающих файлов и принудительная повторная генерация охватывают разные данные. Без шаблонов файлов --force охватывает все настроенные исходные и целевые локали и может заменить принятые переводы. Указывайте шаблоны явно и проверяйте предварительную оценку перед принудительным запуском. При изменении команды отправки обратитесь к разделу Push.

Восстановите работу или отключите пайплайн #

По сообщению об ошибке определите следующий шаг: исправьте установку пакетов, предоставьте переменную с нужными правами доступа, завершите проверку, разрешите конфликт слияния или повторите перевод, который завершился с ошибкой, после устранения её причины. Сохраняйте успешно полученные артефакты, но явно отмечайте частично завершённый выпуск как незавершённый.

Отключите триггер, чтобы остановить новые запуски пайплайна. При отмене работы раннера отдельно проверьте уже отправленные задания на перевод. Когда откажетесь от этой настройки, удалите устаревшие учётные данные API и репозитория.