Рецепт CI для GitHub Actions
Запустите перевод в доверенном задании GitHub Actions, проверьте артефакты и настройте отправку через пул-реквест, когда результат будет готов.
Запускайте Lingo.dev CLI в GitHub Actions, когда для перевода нужны триггеры и проверки существующего пайплайна. Раннер читает конфигурацию репозитория, отправляет изменения исходных файлов и скачивает переводы. Вы решаете, оставить файлы в виде артефактов или создать пул-реквест.
Начните с ручного запуска и доступа к репозиторию только для чтения. Проверив перевод одного изменённого сообщения, вы можете добавить права на запись, необходимые для пул-реквеста с переводом. Для управляемой обработки репозитория используйте встроенную интеграцию GitHub App — она не требует настройки раннера по этому рецепту.
Подготовьте репозиторий #
Локально пройдите краткое руководство по CLI с одним исходным файлом и одним целевым языком. Добавьте в коммит .lingo/config.json, проверенный целевой файл и .lingo/lock.json. Конфигурация задаёт движок локализации, исходную и целевые локали, а также шаблоны файлов. Lockfile фиксирует базовое состояние для последующих изменений исходных файлов.
Для примера ниже укажите locales/en.json как источник, а испанский — как целевой язык, чтобы получить locales/es.json. Первый отсутствующий целевой файл создаётся с помощью lingo push --backfill-missing --wait, а последующие изменения исходного файла обрабатываются с помощью lingo push --wait. Backfill выбирает отсутствующие целевые файлы, поэтому не восстанавливает недостающие ключи в уже существующем файле.
Добавьте LINGO_API_KEY в секреты Actions репозитория или окружения. Этот секрет даёт доступ к Lingo.dev независимо от прав в репозитории GitHub. Запускайте задание с учётными данными только на доверенном коде. В частности, не используйте pull_request_target для checkout и выполнения кода из недоверенной головной ревизии пул-реквеста с доступом к секрету.
В примере версия CLI зафиксирована. Чтобы управлять ею через зависимости проекта и Lockfile, следуйте руководству по настройке CI.
Получите артефакт с переводом #
Сохраните этот пример как .github/workflows/translate.yml. В нём используется Node.js 22.
name: Translate catalog
on:
workflow_dispatch:
permissions:
contents: read
jobs:
translate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
- name: Translate and download
# Replace 1.21.0 with the current CLI version.
run: npx -y @lingo.dev/cli@1.21.0 push --wait
env:
LINGO_API_KEY: ${{ secrets.LINGO_API_KEY }}
- name: Inspect expected output
run: |
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
- uses: actions/upload-artifact@v4
with:
name: translated-catalog
include-hidden-files: true
path: |
locales/es.json
.lingo/lock.jsonПроверьте ИД организации и движка в файле .lingo/config.json, сохранённом в коммите. Внесите одно изменение в английский исходный текст, создайте коммит и запустите рабочий процесс из этой доверенной ветки. Проверьте результат запуска и различия в логе задания. Затем скачайте артефакт и найдите запись на испанском, которая соответствует вашему изменению. Загрузите её через приложение и проверьте смысл и переменные.
В артефакт включаются скрытые файлы, чтобы сохранить .lingo/lock.json. Ограничьте список путей нужным целевым файлом и Lockfile. Не добавляйте в него учётные данные и другие скрытые файлы с закрытой информацией.
Проверки в оболочке подтверждают наличие файлов и корректность синтаксиса JSON. Старый целевой файл тоже может пройти обе проверки, поэтому важно проверить изменённую запись. Если движок локализации требует ручной проверки, запуск может всё ещё ожидать решения человека после завершения команды. Прежде чем использовать такую политику на одноразовом раннере, добавьте процедуру сохранения состояния запуска CI. После отправки экспортируйте указатель на конкретный запуск и исходный абсолютный путь к корню проекта. Загрузите .lingo-ci/run.json, .lingo-ci/project-root.txt, .lingo/config.json, locales/en.json, целевой файл и Lockfile как артефакты с ограниченным доступом. Используйте if: always() на шагах экспорта и загрузки, чтобы сбой последующей проверки не привёл к потере состояния, которое можно восстановить. Если указателя нет, выясните, что произошло при отправке, а не создавайте его наугад.
После проверки восстановите именно эту ревизию и состояние файлов по сохранённому абсолютному пути к корню проекта. Восстановите указатель, отдельно пройдите аутентификацию и используйте Pull с проверкой конфликтов. Если другой раннер не может воссоздать этот путь, отправляйте изменения и получайте результат на постоянном раннере с нужными правами. Не считайте старый целевой файл из первого артефакта завершённым переводом.
push --wait ожидает завершения и скачивает доступный готовый результат. Без --wait команда push обычно завершается после отправки. Если отправка и получение выполняются в разных заданиях, нужны те же экспорт и восстановление состояния запуска. Одного копирования Lockfile недостаточно. Храните скачанные целевые файлы вместе с Lockfile из той же завершённой операции и никогда не архивируйте ~/.lingo целиком.
Создайте пул-реквест #
После успешной проверки артефактов предоставьте заданию права contents: write и pull-requests: write. Политика репозитория тоже должна разрешать Actions создавать пул-реквесты. GITHUB_TOKEN даёт права на эти операции в GitHub, а LINGO_API_KEY оставьте для перевода.
Настройте имя и почту автора коммитов Git по правилам вашей команды для ботов. Затем после проверки результата добавьте шаг, который помещает в индекс только ожидаемый целевой файл и Lockfile:
git add locales/es.json .lingo/lock.json
git diff --cached --quiet && exit 0
branch="lingo/translations-${GITHUB_RUN_ID}"
git switch -c "$branch"
git commit -m "chore: update translations"
git push origin "$branch"
gh pr create --fill --base "$GITHUB_REF_NAME" --head "$branch"На раннерах, размещённых в GitHub, уже установлен GitHub CLI. Передайте этому шагу GH_TOKEN из secrets.GITHUB_TOKEN. Эта последовательность рассчитана на ручной запуск из доверенной ветки и новое имя ветки. При повторном запуске с уже существующей веткой нужно явно решить, использовать её повторно или заменить. Этот рабочий процесс не предназначен для записи изменений обратно в форк.
Пул-реквест направлен в ветку, из которой вы запустили задание. Если GitHub помечает рабочие процессы пул-реквеста как ожидающие одобрения, кто-то с правом записи в репозиторий должен выбрать Одобрить запуск рабочих процессов. См. описание работы GITHUB_TOKEN в GitHub. Перед слиянием проверьте изменения перевода, результаты проверок и результат в приложении.
Если политика ветки позволяет, вы можете создавать коммиты прямо в ветке, из которой запущено задание. Но тогда отдельного этапа проверки содержимого не будет и понадобится защита от зацикливания.
Настройте запуски и работу с монорепозиториями #
Когда первый запуск даст полезный результат, добавьте запуск при push в доверенные ветки и фильтры по путям исходных файлов. Созданные коммиты с переводами не должны бесконечно запускать новые задания перевода. Сочетайте подходящие фильтры веток или путей с выходом при отсутствии изменений на шаге отправки результата.
Для монорепозитория задайте папку пакета с .lingo/config.json как рабочую папку шага перевода. Обновите пути к артефактам и файлам для добавления в индекс, включив в них этот пакет. Матрица может обрабатывать независимые пакеты, но два её элемента не должны одновременно обновлять одну и ту же конфигурацию и Lockfile. У всех элементов одного запуска общий ИД запуска, поэтому задайте каждому своё имя артефакта и отдельную ветку перевода. Например, добавьте имя пакета к translated-catalog и lingo/translations-${GITHUB_RUN_ID}.
Восстановите незавершённый запуск #
Начните с указанного состояния: устраните ошибки целевых переводов со сбоем, примите решения по переводам, ожидающим проверки, а при локальных конфликтах получения выберите между локальным изменением и скачанным результатом. Сохраните успешные результаты для проверки, а незавершённые локали оставьте в незавершённом состоянии. Частичный результат не должен считаться полным релизом локали.
Не скрывайте ненулевые коды завершения. || true, принудительное получение поверх локальных изменений или принудительная обработка всех целевых переводов могут скрыть причину сбоя и заменить уже принятую работу. В руководстве по рабочему процессу CI описано, как сохранить ревизию и базовое состояние при восстановлении.
Отключите рабочий процесс или его триггер, чтобы остановить запуск новых заданий на раннерах. Если задание уже отправило текст на перевод, при отмене Actions отдельно проверьте соответствующий запуск на сервере. Когда рабочий процесс больше не нужен, удалите неиспользуемые секреты и отзовите права на запись в репозиторий.