Сценарий для Bitbucket Pipelines

Запускайте перевод файлов в Bitbucket Pipelines, сохраняйте результат коммитом в репозиторий и отклоняйте пул-реквесты с устаревшими переводами.

Используйте пайплайн Bitbucket, чтобы переводить исходные файлы, выбранные в конфигурации Lingo.dev. CLI отправляет задание и скачивает целевые файлы, а пайплайн определяет, как их сохранить и доставить. В этом сценарии мы начнём с пользовательского пайплайна с ручным запуском: вы сможете проверить один перевод, прежде чем настраивать регулярные запуски.

Подключение работает через вызов API из раннера, а не через встроенный коннектор учётной записи Bitbucket. Для записи в репозиторий и создания пул-реквестов нужны отдельные разрешения Bitbucket.

Подготовьте один рабочий каталог #

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

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

Сохраните LINGO_API_KEY как защищённую переменную репозитория. CLI читает только переменную с этим именем, а LINGODOTDEV_API_KEY из предыдущей версии CLI игнорирует — переименуйте её. Запускайте пайплайн на доверенном коде и отключайте трассировку команд оболочки при работе с учётными данными. Даже защищённую переменную небезопасно передавать произвольным скриптам из пул-реквеста.

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

Переведите файлы и сохраните результат #

Добавьте этот пользовательский пайплайн в bitbucket-pipelines.yml:

yaml
image: node:22

pipelines:
  custom:
    translate-catalog:
      - step:
          name: Translate and inspect
          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:
            - locales/es.json
            - .lingo/lock.json

Убедитесь, что раннер может скачать CLI из npm. Замените пути к файлам на те, что используются в вашей конфигурации.

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

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

Сохраните состояние отправки и получения результата #

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

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

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

Выберите, как доставить результат в репозиторий #

Артефакта достаточно, если перед доставкой результат должен проверить человек или последующее задание выпуска. Храните вместе переведённые файлы и Lockfile, полученные в рамках одной завершённой операции.

Чтобы проверять изменения перед обновлением репозитория, отправляйте их в ветку переводов, а затем открывайте пул-реквест в Bitbucket или через его документированный API. Шаг может отправлять изменения в свой репозиторий через стандартный origin без дополнительных учётных данных, как показано в следующем разделе. Добавляйте SSH-ключ репозитория или токен доступа, только если права доступа к ветке блокируют отправку или если нужно создать пул-реквест через API. Для этого API требуется право на запись пул-реквестов. Укажите бота команды как автора коммитов, добавляйте в индекс только известные целевые пути и .lingo/lock.json и завершайте шаг, если в индексе нет изменений. Используйте разные имена веток или осознанно используйте ветки повторно, чтобы параллельные запуски не перезаписывали результаты друг друга.

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

Храните ключ API Lingo.dev отдельно от учётных данных репозитория. Передавайте его в окружение процесса перевода — никогда не добавляйте в адрес удалённого репозитория Git, файл в коммите или артефакт с результатом. Добавляйте в индекс конкретные пути вместо git add ., чтобы не захватить посторонние файлы раннера.

Коммит переводов обратно в ветку #

Этот пайплайн ветки переводит каждое изменение, попавшее в main, и сохраняет результат коммитом в main. Предполагается, что первоначальный полный перевод уже сохранён коммитом, а «Ручная проверка» в движке отключена, поэтому перевод завершается за один шаг. Добавьте раздел branches этого пайплайна под тем же ключом pipelines, что и у пайплайна с ручным запуском. Полный файл будет выглядеть так:

yaml
image: node:22

pipelines:
  custom:
    translate-catalog:
      - step:
          name: Translate and inspect
          script:
            - 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:
            - locales/es.json
            - .lingo/lock.json
  branches:
    main:
      - step:
          name: Translate and commit
          auth:
            system:
              scopes:
                - read:git:bitbucket
                - write:git:bitbucket
          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 "[skip ci] Update translations"
            - git push origin "HEAD:$BITBUCKET_BRANCH"

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

Pipelines настраивает удалённый репозиторий origin, чтобы шаг мог отправлять изменения обратно в свой репозиторий без дополнительных учётных данных. Блок auth шага даёт встроенному токену право выполнять Git push. С 30 апреля 2027 года Bitbucket больше не предоставляет это право шагам без блока auth. Для использования auth на собственных раннерах нужна версия раннера 6.1.0 или новее. Если ограничение для ветки main блокирует push, добавьте main как исходную ветку в настройках доступа Pipelines на запись для этого ограничения. Другой вариант — предоставить шагу SSH-ключ или токен доступа с правом записи, как описано в руководстве Bitbucket по отправке изменений обратно в репозиторий.

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

Настройте триггеры и пути к пакетам #

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

Автоматически созданные коммиты не должны запускать перевод по бесконечному кругу. Выберите нужные пути исходных файлов и доверенные ветки, примените подходящее правило для автоматически созданных коммитов и сохраните завершение работы при отсутствии изменений. Если исходный текст не менялся, отсутствие различий — нормальный результат.

Если конфигурация находится в apps/web/.lingo/config.json, запускайте CLI из apps/web. Пути к артефактам пайплайна по-прежнему задаются относительно репозитория по правилам Bitbucket, поэтому используйте пути вроде apps/web/locales/es.json и apps/web/.lingo/lock.json. Смена рабочего каталога CLI не меняет правила указания путей к артефактам.

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

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

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

Эта проверка предназначена для конфигурации без описанного выше пайплайна ветки. Почему — объясняет таблица ниже. Добавьте раздел pull-requests под ключом pipelines, рядом с custom, если оставляете пайплайн с ручным запуском. Если использовать только эту проверку, файл будет выглядеть так:

yaml
image: node:22

pipelines:
  pull-requests:
    "**":
      - step:
          name: Check translations
          script:
            # lingo check needs CLI 1.20.0 or newer.
            - npx -y @lingo.dev/cli@1.21.0 check

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

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

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

Восстановите недостающий результат или остановите работу #

Если результата нет, проверьте выбранные исходные файлы, базовое состояние, охват целевых файлов, доступность защищённых переменных, состояние проверки и сообщения об ошибках. Восстановите записанный запуск, прежде чем отправлять новое задание. Перед созданием недостающих целевых файлов в существующем проекте завершите обычные обновления уже существующих целевых файлов, получите и проверьте результаты. Затем не меняйте ревизию исходного текста, пока недостающие файлы не будут созданы. Эта последовательность описана в разделе «Как добавить язык». Используйте принудительную повторную генерацию, только если намерены заменить выбранный текст, который уже был принят. В разделе «Восстановление после неудачного запуска» описано, как запросить ещё одну попытку без принудительной замены.

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