Сценарий для Buildkite

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

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

Это сценарий для CI, а не встроенная интеграция с Buildkite. Начните с одного шага перевода в ветке по умолчанию или в сборках пул-реквестов и проверьте его первый коммит. Добавляйте проверку пул-реквестов только в тех случаях, для которых она подходит по таблице.

Подготовка репозитория и агента #

Локально выполните инструкцию по быстрому старту с CLI. Добавьте в коммит .lingo/config.json, принятые целевые файлы и .lingo/lock.json. Конфигурация задаёт исходную и целевые локали, шаблоны файлов и движок локализации. В примерах исходный файл — locales/en.json, а существующий целевой файл на испанском — locales/es.json. Если целевых файлов больше, выполните test -s и проверки JSON для каждого из них. В остальных командах, где указан locales/es.json, перечислите пути ко всем целевым файлам или добавьте в индекс весь каталог с ними, например locales/. Lockfile отмечает исходный файл как переведённый, поэтому при следующей отправке он будет пропущен, а целевой файл, не попавший в коммит, останется устаревшим.

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

Агенту нужны Node.js, npm и Git, а также сетевой доступ к реестру npm и Lingo.dev. Учётные данные репозитория, которые агент использует для checkout, например ключ развёртывания, должны также разрешать отправку изменений в ветку, куда шаг записывает результат.

Сохраните ключ API Lingo.dev как секрет Buildkite с именем LINGO_API_KEY. CLI читает только это имя. Переменная LINGODOTDEV_API_KEY из предыдущего CLI игнорируется, поэтому переименуйте её. Загружайте секрет только в шаге перевода. Для ключа secrets: этого шага нужен агент Buildkite версии 3.106.0 или новее, работающий в кластере, где хранится секрет. С более ранними версиями агента пайплайн завершится с ошибкой. На старых агентах или агентах вне кластера удалите secrets: и вместо этого экспортируйте LINGO_API_KEY для этого шага через хук агента environment или плагин для секретов.

Не включайте параметр Разрешить сборки из сторонних форков репозиториев в настройках GitHub пайплайна. Пул-реквест из форка собирается с собственным pipeline.yml, куда можно добавить шаг для чтения секрета. Никакой if: в вашем файле этому не помешает. Также добавьте к секрету политику доступа, чтобы читать его могли только сборки этого пайплайна.

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

Перевод и отправка результата в ту же ветку #

Этот шаг переводит каждое изменение, попавшее в ветку по умолчанию, и отправляет результат в ту же ветку. Предполагается, что первоначально недостающие переводы уже добавлены в коммит, а в движке отключена ручная проверка, поэтому перевод завершается за один шаг. Добавьте его в .buildkite/pipeline.yml:

yaml
steps:
  - label: "Translate"
    if: build.branch == pipeline.default_branch && build.pull_request.id == null
    concurrency: 1
    concurrency_group: "lingo-translations"
    # secrets: needs Buildkite agent 3.106.0 or later.
    secrets:
      - LINGO_API_KEY
    command: |
      # 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 "[skip ci] Update translations"
      git push origin "HEAD:refs/heads/$${BUILDKITE_BRANCH}"

--wait позволяет шагу дождаться завершения запуска и записать переведённые файлы в checkout. Без него lingo push только отправляет задание на выполнение и завершает работу, поэтому шагу нечего добавить в коммит. Если перевод целевого файла завершается с ошибкой, lingo push --wait возвращает ненулевой код выхода и шаг останавливается до коммита. Когда изменений нет, команда выводит «Нечего отправлять», подготовленных изменений нет и шаг завершается без коммита.

Buildkite выполняет checkout отдельного коммита, а не ветки, поэтому в команде отправки явно указана ветка. $$ оставляет BUILDKITE_BRANCH для подстановки оболочкой во время выполнения шага. С одиночным $ Buildkite записал бы имя ветки в текст команды при загрузке пайплайна. concurrency и concurrency_group позволяют выполнять только один перевод за раз. Если за время перевода в ветке появились новые коммиты, Git отклонит отправку. Изменения переведёт сборка для более нового коммита.

Шаг не зацикливается. Buildkite пропускает сборки для коммитов, в сообщении которых есть [skip ci]. Без него следующая сборка не нашла бы ничего для отправки, потому что добавленный в коммит .lingo/lock.json уже учитывает новый исходный файл.

При отправке прямо в ветку по умолчанию переводы не проходят проверку в отдельном пул-реквесте. Выбирайте такую политику работы с веткой осознанно. Чтобы сначала проверять переводы, отправляйте их в отдельную ветку, например lingo/translations, и открывайте пул-реквест средствами вашей Git-платформы.

Перевод в сборках пул-реквестов #

Чтобы переводить изменения исходных файлов каждого пул-реквеста в его собственной ветке, используйте этот шаг вместо шага для ветки по умолчанию. Для него действуют те же условия. Его if: пропускает пул-реквесты из форков, потому что шаг не может отправлять изменения в ветку форка.

Для этого шага нужно изменить два параметра в настройках GitHub пайплайна. Включите Запускать сборку при открытии или обновлении пул-реквеста. Выключите Собирать ветки или ограничьте этот параметр веткой по умолчанию. Если сборки веток включены, отправка изменений в ветку пул-реквеста может запустить сборку без сведений о пул-реквесте. Шаг пропустит такую сборку: ничего не переведёт и не завершится с ошибкой.

if: не защищает LINGO_API_KEY. Buildkite читает его из собственного pipeline.yml пул-реквеста, а в форке этот файл можно изменить. Поэтому сборки форков должны оставаться выключенными, как указано в инструкции по настройке. Пул-реквест из ветки того же репозитория тоже может изменить файл, поэтому любой человек с правом отправки изменений в ветку сможет прочитать ключ через этот шаг. Используйте шаг только там, где всем с правом отправки изменений разрешён доступ к ключу.

yaml
steps:
  - label: "Translate pull request"
    if: build.pull_request.id != null && build.pull_request.repository.fork != true
    # secrets: needs Buildkite agent 3.106.0 or later.
    secrets:
      - LINGO_API_KEY
    command: |
      # 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 origin "HEAD:refs/heads/$${BUILDKITE_BRANCH}"

В сообщении коммита намеренно нет [skip ci]. Buildkite запускает сборку коммита с переводом, шаг выполняется снова, не находит ничего для отправки и завершается без коммита. Цикл заканчивается после одной дополнительной сборки. Эта сборка присваивает статус последнему коммиту пул-реквеста. С [skip ci] для последнего коммита не было бы сборки Buildkite, а обязательная проверка статуса Buildkite заблокировала бы слияние.

Учётные данные агента для checkout должны разрешать отправку изменений в ветки пул-реквестов. Если за время перевода в ветке появились новые коммиты, Git отклонит отправку и шаг завершится с ошибкой. Изменения переведёт сборка для более нового коммита. Поэтому две отправки подряд запускают два перевода, и оплачиваются оба. Включите Отменять промежуточные сборки в настройках пайплайна, чтобы новая отправка отменяла предыдущую сборку. Перевод, который предыдущая сборка уже отправила на выполнение, не отменяется.

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

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

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

Добавьте этот шаг в .buildkite/pipeline.yml, если по таблице ниже такая проверка подходит для вашей конфигурации. Шаг рассчитан на конфигурацию, в которой не используется ни один из двух шагов перевода выше. Поэтому каждый пример здесь — полный список steps: для одной конфигурации. Включите шаг из примера в существующий список steps:, а не добавляйте второй ключ steps::

yaml
steps:
  - label: "Check translations"
    if: build.pull_request.id != null
    command:
      # lingo check needs CLI 1.20.0 or newer.
      - npx -y @lingo.dev/cli@1.21.0 check

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

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

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

Адаптация шага #

В монорепозитории запускайте CLI из пакета, в котором находится .lingo/config.json, например добавив cd apps/web в начало команды. Добавляйте в индекс целевые файлы и Lockfile этого пакета. Независимые пакеты хранят отдельные Lockfile и могут использовать разные движки локализации.

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

Восстановление работы и отключение шага #

Сообщение об ошибке подскажет, что делать дальше: исправить установку пакетов, передать секрет, завершить проверку, устранить конфликт при получении изменений или устранить причину сбоя и повторить перевод целевых файлов. Не скрывайте ненулевые коды выхода: || true скрывает причину ошибки.

Чтобы остановить новые сборки, удалите шаг или его триггер. При отмене сборки отдельно проверьте уже отправленный на выполнение перевод. Когда сценарий больше не нужен, удалите секрет LINGO_API_KEY и отзовите у агента право записи.