Автоматизируйте переводы в CI
Сделайте перевод воспроизводимой частью выпуска: от известной ревизии исходников до проверенных файлов и проверок приложения.
Пайплайн выпуска уже связывает ревизию исходников с продуктом, которым могут пользоваться люди. Перевод должен сохранять эту связь. Заданию нужно знать, какие исходники изменились, получить соответствующие файлы перевода и передать следующему этапу достаточно данных, чтобы принять или отклонить результат.
Сложности начинаются после первого успешного запроса: проверяющий ещё вносит правки, раннер становится недоступен или появляется новая версия исходного текста, пока перевод предыдущей ещё не готов. В этом руководстве мы выстроим процесс CI, который справится с такими ситуациями: не опубликует устаревшие файлы и не заменит принятые правки без необходимости. YAML для каждой платформы вы найдёте в примерах настройки GitHub Actions, GitLab, Bitbucket и Buildkite.
Решите, на каком этапе выпуска добавлять переводы #
Используйте управляемое GitHub App, если вам подходит его рабочий процесс для репозитория. Изменения в основной ветке приводят к созданию пул-реквеста с переводами. Если включить обработку пул-реквестов, переводы будут записываться в ветку соответствующего пул-реквеста. Одобрение запуска разрешает начать перевод. Проверка содержимого и слияние происходят позже.
Если вы используете раннер с CLI, ваш пайплайн отвечает за отправку, получение и доставку переводов. Выберите, куда сохранять результат, с учётом процесса выпуска:
| Куда сохранять | Какое решение позволяет принять |
|---|---|
| Только артефакт | Другое задание или человек проверяет результат до внесения изменений в репозиторий или выпуск. |
| Ветка переводов и пул-реквест | Проверить изменения в переводах отдельно, прежде чем они попадут в основную ветку. |
| Ветка исходного пул-реквеста | Проверить исходники и переводы вместе, в одном изменении. |
| Коммит прямо в основную ветку | Доставить переводы без отдельного пул-реквеста, если политика ветки явно это разрешает. |
Для каждого состояния перевода разрешайте запись в репозиторий только одному активному процессу. Иначе два раннера с разными ревизиями исходников могут конкурировать за запись файлов и Lockfile в коммиты. Для автоматически созданных коммитов также нужны правила по веткам, путям или признаку такого коммита, чтобы они не запускали перевод снова и снова.
Подготовьте базовое состояние для раннера #
Прежде чем включать регулярные запуски, локально переведите один исходный файл на один язык и выполните проверки ресурсов приложения. Сохраните конфигурацию, принятый перевод и .lingo/lock.json в одном коммите. Чистый checkout должен давать тот же набор исходников и ту же структуру файлов перевода.
В примерах для платформ закреплена версия @lingo.dev/cli@1.21.0. При настройке рабочего процесса замените её на текущую версию CLI. Чтобы управлять CLI через зависимости проекта, установите его с помощью npm install --save-dev --save-exact @lingo.dev/cli@1.21.0 и добавьте package.json и package-lock.json в коммит. Затем используйте npm ci и npx --no-install lingo, чтобы запускать версию, записанную в Lockfile.
.lingo/config.json задаёт локали, шаблоны файлов и движок локализации. Во время настройки обеспечьте доступ к организации и движку локализации. Если заданию нужно инициализировать или связать проект, используйте явные параметры из справочников Инициализация и Связывание. Не оставляйте задание ждать ответа на интерактивный запрос при запуске без участия человека.
В монорепозитории перед запуском CLI перейдите в пакет с нужной конфигурацией. Позиционные шаблоны сужают набор исходников, выбранных этой конфигурацией, но не выбирают конфигурацию другого пакета. Храните вместе состояние и пути артефактов каждого пакета с независимой конфигурацией.
Передавайте LINGO_API_KEY через механизм секретов раннера. Интерактивный вход для этого не нужен. Запускайте задания с учётными данными только для доверенного кода: в ветке можно изменить скрипты так, чтобы раскрыть ключ. Ограничения для защищённых переменных и форков должны определять, где запускается задание. Не снимайте их ради успешного запуска недоверенного задания.
Отправляйте нужный тип задач #
При первом переводе с нуля запросите недостающие файлы перевода. В существующем проекте сначала обработайте обычные изменения исходников для уже имеющихся переводов, получите и проверьте результаты. Затем добавьте недостающие локали и заполните их переводы, не меняя ревизию исходников. Перед этой командой выполните шаги из раздела Как добавить язык:
lingo push --backfill-missing --waitДля изменений исходников относительно подготовленного базового состояния:
lingo push --waitПервый обычный push может зафиксировать состояние исходников, не переводя их. Заполнение недостающих файлов создаёт задачу на их перевод. При последующих обычных push объём работы определяется изменениями исходников. Push с ограниченной областью или заполнением недостающих файлов — не универсальный способ восстановить отсутствующие ключи в существующих файлах перевода.
--wait дожидается завершения запуска и скачивает готовый результат. Без этого параметра push возвращает управление после отправки. Если нужно дождаться проверки или получить результат отдельным заданием, следуйте процедуре сохранения состояния запуска CI: до завершения работы раннера сохраните конкретный указатель в домашнем каталоге, не содержащий секретов, исходный абсолютный путь к корню проекта и соответствующее состояние исходников, конфигурации, переводов и Lockfile. Восстановите всё по тому же корневому пути и отдельно пройдите аутентификацию, прежде чем использовать lingo pull --dry-run, а затем lingo pull. Если раннер не может воссоздать этот путь, используйте постоянный checkout с авторизованным доступом. Никогда не архивируйте учётные данные или весь ~/.lingo.
Сохраняйте код завершения и результаты, о которых сообщено для целевых локалей. Текущая версия CLI завершается с ошибкой, если сообщается о сбое для целевой локали, но при ручной проверке запуск может остаться в ожидании решений. Пока новая версия ждёт проверки, старый файл может оставаться на месте. Завершите проверку и получите результат, прежде чем разрешать заданию доставки публиковать его.
Точное поведение команд описано в разделах Отправка и Получение. --yes пропускает подтверждение принудительной повторной генерации. Этот параметр не заменяет одобрение при ручной проверке и не превращает все ожидающие действия в завершённые.
В CI CLI пропускает проверку обновлений. При необходимости LINGO_DISABLE_UPDATE_CHECK=1 и LINGO_TELEMETRY_DISABLED=1 позволяют явно управлять этим, не отключая обмен данными для перевода.
Убедитесь, что следующий этап получит готовые к работе файлы #
Сверьте запись, в которой ожидаете изменения, с ревизией исходников. Само наличие файла мало что доказывает, если checkout уже содержит старый перевод. Сохраняйте скачанный результат и состояние Lockfile от одной и той же операции. Локали со сбоем или в ожидании должны явно оставаться незавершёнными.
Затем выполните проверки, которые учитывают формат ресурса:
- При извлечении строк из React выполните
lingo extract --check,lingo check, проверку TypeScript в проекте и полноценную сборку приложения. Эти проверки охватывают разные части результата. - Для нативных ресурсов запустите генерацию или компиляцию ресурсов средствами платформы.
- Для статического содержимого выполните разбор переведённых документов и проверьте ссылки, переменные и сохранность синтаксиса.
- Чтобы запрос на слияние не проходил проверку при устаревших переводах, запустите
lingo check. Ключ API не нужен.
lingo check работает на уровне файлов: сообщает об изменённом исходнике и недостающем файле перевода для каждой настроенной локали, но не об отсутствующем ключе внутри существующего файла Android, Apple, ARB или Markdoc.
Проверяйте смысл перевода в рамках выбранного процесса приёмки. Сборка может выявить некорректный формат ресурса, но пропустить предложение, которое меняет важное условие. После успешных автоматических проверок и проверки перевода добавляйте в коммит или публикуйте только файлы по нужным путям. Предусмотрите выход без коммита, если изменений нет. Ошибки обязательных проверок должны завершать задание с ошибкой — не маскируйте их безусловным коммитом.
Возобновляйте сохранённую работу, прежде чем запускать её заново #
После прерывания задания восстановите идентификатор запуска и результаты по целевым локалям. Если перевод завершён, получите результат, прежде чем отправлять новый запрос. Если локальный файл перевода изменился за время ожидания, разрешите конфликт при получении результата так, чтобы принятая правка оставалась перед глазами. Принудительная перезапись может удалить именно то исправление, которое рабочий процесс должен сохранить.
Не удаляйте Lockfile во время диагностики. Его удаление меняет базовое состояние исходников для следующего запуска и может превратить точечное восстановление в другую работу. Изучите различия и повторите только ту часть, которая осталась незавершённой. Подробнее об этом выборе — в разделе Как восстановить прерванный запуск локализации.
Прежде чем включать запуск по расписанию, проверьте не только успешный сценарий, но и ожидание ручной проверки, а также прерванное получение результата. Этап выпуска должен сохранять последнее принятое состояние и указывать незавершённую локаль, а не принимать любой файл, который оказался на месте.