Интеграция Lingo.dev с GitHub

GitHub Action от Lingo.dev — это безопасная, открытая CI/CD интеграция, которая автоматически локализует новый контент и предотвращает попадание неполных переводов в продакшн. Она создает pull request'ы или коммиты напрямую в вашу ветку, в зависимости от требований рабочего процесса вашей команды.

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

Действие поддерживает несколько сценариев рабочего процесса:

Прямые коммиты в основную ветку при слиянии изменений контента
Прямые коммиты в ветки pull request'ов при их создании или обновлении
Pull request'ы, нацеленные на основную ветку, для обновлений переводов
Pull request'ы, нацеленные на существующие ветки pull request'ов, для обновлений переводов

После завершения этого руководства вы сможете:

Настроить автоматическую локализацию, запускаемую при пушах кода;
Настроить безопасную аутентификацию с использованием секретов репозитория;
Выбрать между прямыми коммитами и рабочими процессами с pull request'ами;
Понять, как непрерывная локализация вписывается в ваш существующий процесс.

Начнем!

Предварительные требования

Настройка репозитория

Ваш репозиторий должен быть настроен с CLI Lingo.dev и иметь действующий файл i18n.json. Если вы еще не настроили это, сначала завершите быстрый старт CLI.

Шаг 1. Настройка аутентификации

GitHub Actions от Lingo.dev требует доступа к вашему движку перевода и репозиторию. Аутентификация осуществляется через секреты репозитория, которые обеспечивают безопасность ваших учетных данных.

Добавьте ваш API-ключ

Перейдите в настройки вашего репозитория → Secrets and variables → Actions, затем добавьте учетные данные вашего движка перевода:

Для пользователей сырого API LLM:

Имя секрета: OPENAI_API_KEY или ANTHROPIC_API_KEY
Значение секрета: ваш API-ключ от соответствующего провайдера

Для пользователей движка Lingo.dev:

Имя секрета: LINGODOTDEV_API_KEY
Значение секрета: ваш API-ключ проекта из lingo.dev/app

Шаг 2. Создайте workflow

Создайте файл .github/workflows/i18n.yml в вашем репозитории с этой базовой конфигурацией:

name: Lingo.dev i18n

on:
  workflow_dispatch:
  push:
    branches:
      - main
      - feat/*

permissions:
  contents: write
  pull-requests: write

jobs:
  i18n:
    name: Run i18n
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: lingodotdev/lingo.dev@main
        with:
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

Или вы можете добавить GitHub Action от Lingo.dev как шаг в ваш существующий workflow:

- name: Lingo.dev
  uses: lingodotdev/lingo.dev@main
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

Необходимые разрешения

Ваш workflow требует определённых разрешений для корректной работы. GitHub Actions требует явного указания разрешений в файле workflow:

permissions:
  contents: write # Обязательно: создание коммитов с обновлениями переводов
  pull-requests: write # Необязательно: нужно только при использовании режима pull request

Разрешение contents: write позволяет действию:

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

Эти разрешения предоставляются временным токеном GitHub (${{ github.token }}), который автоматически создаётся GitHub для каждого запуска workflow и имеет ровно те разрешения, которые вы укажете в файле workflow.

Эта конфигурация:

Срабатывает при пушах в основную и feature-ветки
Предоставляет необходимые разрешения для коммитов и pull request'ов
Использует последнюю версию действия для автоматических обновлений
Безопасно получает доступ к вашему API-ключу через секреты репозитория

Бонус:

В Lingo.dev мы рекомендуем добавлять триггер workflow_dispatch в каждый workflow, чтобы можно было вручную запускать его (или перезапускать) из интерфейса GitHub Actions. Это полностью опционально, но мы нашли это очень полезным.

Шаг 3. Выберите режим рабочего процесса

Lingo.dev GitHub Actions поддерживает два режима работы в зависимости от требований вашей команды к проверке кода.

Режим прямого коммита (по умолчанию)

Действие напрямую коммитит переводы в вашу ветку:

- uses: lingodotdev/lingo.dev@main
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

Этот режим лучше всего подходит для:

Индивидуальных разработчиков или небольших команд
Функциональных веток, которые будут проверены перед слиянием
Проектов, где обновления переводов не требуют отдельной проверки

Режим Pull Request

Действие создает pull request для обновлений переводов:

- uses: lingodotdev/lingo.dev@main
  env:
    GH_TOKEN: ${{ github.token }}
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
    pull-request: true
    pull-request-title: "feat: update translations"

Необходимые разрешения для режима Pull Request

Режим pull request требует дополнительных разрешений и настроек репозитория:

permissions:
  contents: write # Обязательно: доступ к содержимому репозитория и создание коммитов
  pull-requests: write # Обязательно: создание и обновление pull request

Настройка токена GitHub: Переменная окружения GH_TOKEN должна быть установлена в значение ${{ github.token }}, который является временным токеном, автоматически создаваемым GitHub для каждого запуска рабочего процесса. Этот токен имеет ровно те разрешения, которые указаны в разделе permissions вашего файла рабочего процесса.

Настройки репозитория: Необходимо включить возможность для GitHub Actions создавать pull request в настройках вашего репозитория:

Перейдите в Настройки → Actions → Общие
Пролистайте страницу вниз
В разделе "Разрешения рабочего процесса" убедитесь, что включена опция "Разрешить GitHub Actions создавать и одобрять pull request"

Если вы не видите эту опцию в настройках репозитория, проверьте настройки вашей организации:

Перейдите в Настройки вашей организации → Actions → Общие
Найдите ту же настройку "Разрешить GitHub Actions создавать и одобрять pull request"

Этот режим лучше всего подходит для:

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

Шаг 4. Сценарии рабочего процесса

Lingo.dev GitHub Action автоматически адаптируется к различным рабочим процессам разработки. Понимание этих сценариев поможет вам выбрать правильную конфигурацию для вашей команды.

Сценарий 1: Обновления основной ветки (прямые коммиты)

Триггер: Пуш в основную ветку (например, при слиянии pull-запросов) Действие: Коммитит обновления переводов напрямую в основную ветку

on:
  push:
    branches: [main]

# Действие коммитит напрямую в основную ветку

- uses: lingodotdev/lingo.dev@main
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

Поток: Изменения контента пушатся в main → Действие коммитит переводы в main

Этот сценарий гарантирует, что ваша основная ветка всегда содержит актуальные переводы сразу после слияния изменений контента.

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

Сценарий 2: Обновления pull-запросов (прямые коммиты)

Триггер: Открытие или обновление pull-запроса с изменениями контента Действие: Коммитит обновления переводов напрямую в ветку pull-запроса

on:
  pull_request:
    types: [opened, synchronize]

# Действие коммитит напрямую в ветку PR

- uses: lingodotdev/lingo.dev@main
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

Поток: Изменения контента в ветке PR → Действие коммитит переводы в ту же ветку PR

Это сохраняет обновления переводов в рамках feature-ветки, обеспечивая их проверку вместе с оригинальными изменениями.

Сценарий 3: Pull-запросы в основную ветку (режим pull-запросов)

Триггер: Пуш в основную ветку (например, при слиянии pull-запросов) Действие: Создает pull-запрос с обновлениями переводов

on:
  push:
    branches: [main]

# Действие создаёт PR: main/lingo.dev → main

- uses: lingodotdev/lingo.dev@main
  env:
    GH_TOKEN: ${{ github.token }}
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
    pull-request: true

Процесс: Изменения контента отправляются в main → Действие создаёт ветку main/lingo.dev → Открывается PR из main/lingo.dev → main

Сценарий 4: Pull Requests в функциональные ветки (режим Pull Request)

Триггер: Открыт или обновлён pull request с изменениями контента Действие: Создаёт pull request с обновлениями перевода, нацеленными на функциональную ветку

on:
  pull_request:
    types: [opened, synchronize]

# Действие создаёт PR: feat/new-feature/lingo.dev → feat/new-feature

- uses: lingodotdev/lingo.dev@main
  env:
    GH_TOKEN: ${{ github.token }}
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
    pull-request: true

Процесс: Изменения контента в feat/new-feature → Действие создаёт ветку feat/new-feature/lingo.dev → Открывается PR из feat/new-feature/lingo.dev → feat/new-feature

Это позволяет проводить отдельные проверки перевода для каждой функциональной ветки.

Конвенция именования веток

При использовании режима pull request GitHub Action Lingo.dev следует единому шаблону именования:

Формат: <основная-ветка>/lingo.dev

Примеры:

Обновления основной ветки: main/lingo.dev → main
Обновления функциональной ветки: feat/user-auth/lingo.dev → feat/user-auth
Обновления релизной ветки: release/v2.0/lingo.dev → release/v2.0

Эта конвенция именования обеспечивает чёткую идентификацию веток перевода и их автоматическую связь с исходными ветками.

Работа с внешними вкладчиками

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

jobs:
  i18n:
    name: Run i18n
    runs-on: ubuntu-latest
    permissions:
      actions: write
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - run: find locales/** -name "*.json" | xargs git checkout ${{ github.event.pull_request.head.sha }} --
        shell: bash
      - uses: lingodotdev/lingo.dev@main
        with:
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

Необходимые разрешения для внешних вкладчиков

Обработка внешних форков требует повышенных разрешений для безопасной обработки вкладов:

permissions:
  actions: write # Обязательно: доступ к информации о workflow и артефактам
  contents: write # Обязательно: создание коммитов и доступ к содержимому репозитория
  pull-requests: write # Обязательно: обновление pull-запросов из внешних форков

Разрешение actions: write необходимо для:

Доступа к метаданным pull-запросов из внешних форков
Чтения контекста workflow для проверки безопасности
Безопасной обработки артефактов и состояния workflow

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

Этот подход:

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

Расширенная конфигурация

Настройте поведение действия с помощью дополнительных параметров:

- uses: lingodotdev/lingo.dev@main
  env:
    GH_TOKEN: ${{ github.token }}
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
    pull-request: true
    commit-message: "feat: update translations via lingo.dev"
    working-directory: "apps/web"
    version: "latest"
    process-own-commits: false
    parallel: true

Опции конфигурации:

commit-message — Пользовательское сообщение для коммитов перевода
working-directory — Запуск действия в подкаталоге
version — Привязка к определённой версии CLI (не рекомендуется)
process-own-commits — Обработка коммитов, сделанных этим действием
parallel — Включение параллельной обработки задач локализации (по умолчанию: false)

Параллельная обработка

GitHub Action поддерживает параллельную обработку задач локализации, что значительно ускоряет рабочие процессы перевода для крупных проектов. Включите эту функцию, установив parallel: true:

- uses: lingodotdev/lingo.dev@main
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
    parallel: true

При включении действия:

Распределяет задачи локализации между несколькими параллельными рабочими процессами
Использует интеллектуальные алгоритмы распределения задач для максимальной пропускной способности
Предотвращает повреждение файлов и состояния гонки благодаря тщательному управлению параллельностью
Значительно сокращает время обработки для проектов с большим количеством файлов перевода

Эта функция особенно полезна для:

Крупных проектов с обширными требованиями к переводу
Рабочих процессов, обрабатывающих несколько локалей одновременно
Команд, которым требуется более быстрая работа CI/CD конвейеров

Примечание: Параллельная обработка может увеличить использование API. Следите за использованием, если у вас есть строгие ограничения по скорости.

Режим проверки

С помощью флага --frozen вы можете проверить, что все переводы актуальны перед каждым развертыванием в продакшн.

Пример использования флага --frozen в вашем конвейере развертывания:

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx lingo.dev@latest i18n --frozen
      - run: npm run build
      - run: npm run deploy

Флаг --frozen:

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