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

Интеграция Lingo.dev с GitLab CI/CD — это безопасная, открытая интеграция CI/CD, которая автоматически локализует новый контент и предотвращает попадание незавершённых переводов в продакшн. Она создаёт merge-запросы или выполняет коммиты напрямую в вашу ветку, в зависимости от требований рабочего процесса вашей команды.

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

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

Прямые коммиты в ветки при внесении изменений в контент
Merge-запросы, нацеленные на ветки для обновления переводов

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

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

Давайте начнём!

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

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

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

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

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

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

Перейдите в Настройки репозитория → CI/CD → Переменные, затем добавьте учётные данные вашего движка перевода:

Для пользователей API LLM:

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

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

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

Добавьте токен доступа GitLab

Создайте пользовательский токен доступа для операций с репозиторием:

Перейдите в Настройки → Токены доступа → Добавить новый токен
Предоставьте следующие области доступа:
- api
- read_repository
- write_repository
Добавьте токен как переменную репозитория:
- Имя переменной: GL_TOKEN
- Значение переменной: ваш токен доступа GitLab

Важно: Стандартный токен CI job недостаточен. Вы должны создать пользовательский токен доступа, так как стандартный токен не имеет необходимых разрешений для операций с git.

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

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

Создайте или обновите ваш файл .gitlab-ci.yml с этой базовой конфигурацией:

lingodotdev:
  image: lingodotdev/ci-action:latest
  script:
    - echo "Done"

Эта конфигурация использует последнюю версию Docker-образа и автоматически запускает движок перевода.

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

GitLab CI/CD требует доступ к переменным репозитория и git-операциям:

Переменные репозитория:

LINGODOTDEV_API_KEY — требуется для пользователей движка Lingo.dev
OPENAI_API_KEY или ANTHROPIC_API_KEY — требуется для пользователей API LLM
GL_TOKEN — требуется для операций git push и создания merge request

Области действия токена доступа:

api — создание и управление merge request
read_repository — доступ к содержимому репозитория
write_repository — отправка коммитов и создание веток

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

Шаг 3. Выберите режим работы workflow

Интеграция Lingo.dev с GitLab поддерживает два режима работы в зависимости от требований вашей команды к проверке кода.

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

Интеграция напрямую коммитит переводы в вашу ветку:

lingodotdev:
  image: lingodotdev/ci-action:latest
  script:
    - echo "Done"

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

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

Режим merge request

Интеграция создает merge request для обновлений переводов:

lingodotdev:
  image: lingodotdev/ci-action:latest
  variables:
    LINGODOTDEV_PULL_REQUEST: "true"
  script:
    - echo "Done"

Необходимая настройка для режима merge request

Переменные репозитория: И LINGODOTDEV_API_KEY, и GL_TOKEN должны быть настроены как переменные репозитория.

Требования к токену доступа: Ваш GL_TOKEN должен включать область действия api для создания и управления merge request.

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

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

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

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

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

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

lingodotdev:
  image: lingodotdev/ci-action:latest
  script:
    - echo "Done"
  rules:
    - if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH = /^feat/

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

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

Сценарий 2: Запросы на слияние для обновлений (режим запросов на слияние)

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

lingodotdev:
  image: lingodotdev/ci-action:latest
  variables:
    LINGODOTDEV_API_KEY: $MY_LINGODOTDEV_API_KEY # или OPENAI_API_KEY/ANTHROPIC_API_KEY
    LINGODOTDEV_PULL_REQUEST: "true"
    LINGODOTDEV_PULL_REQUEST_TITLE: "feat: update translations"
  script:
    - echo "Done"

Поток: Изменения контента отправляются в ветку → Интеграция создает запрос на слияние с переводами

Это позволяет проводить отдельные проверки для обновлений переводов.

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

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

Пример с движком Lingo.dev:

lingodotdev:
  image: lingodotdev/ci-action:latest
  variables:
    LINGODOTDEV_API_KEY: $MY_LINGODOTDEV_API_KEY
    GL_TOKEN: $MY_GL_TOKEN
    LINGODOTDEV_PULL_REQUEST: "true"
    LINGODOTDEV_PULL_REQUEST_TITLE: "feat: update translations"
    LINGODOTDEV_COMMIT_MESSAGE: "feat: update translations via @lingodotdev"
    LINGODOTDEV_WORKING_DIRECTORY: "apps/web"
    LINGODOTDEV_PROCESS_OWN_COMMITS: "true"
  script:
    - echo "Done"
  rules:
    - if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH = /^feat/

Пример с использованием API LLM:

lingodotdev:
  image: lingodotdev/ci-action:latest
  variables:
    OPENAI_API_KEY: $MY_OPENAI_API_KEY # или ANTHROPIC_API_KEY
    GL_TOKEN: $MY_GL_TOKEN
    LINGODOTDEV_PULL_REQUEST: "true"
    LINGODOTDEV_PULL_REQUEST_TITLE: "feat: update translations"
    LINGODOTDEV_COMMIT_MESSAGE: "feat: update translations via @lingodotdev"
    LINGODOTDEV_WORKING_DIRECTORY: "apps/web"
    LINGODOTDEV_PROCESS_OWN_COMMITS: "true"
  script:
    - echo "Done"
  rules:
    - if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH = /^feat/

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

LINGODOTDEV_API_KEY — Ваш API-ключ движка Lingo.dev, если вы используете движок Lingo.dev
OPENAI_API_KEY — Ваш API-ключ OpenAI, если вы используете API LLM
ANTHROPIC_API_KEY — Ваш API-ключ Anthropic, если вы используете API LLM
LINGODOTDEV_PULL_REQUEST — Создавать запрос на слияние вместо прямого коммита (по умолчанию: false)
LINGODOTDEV_PULL_REQUEST_TITLE — Пользовательский заголовок запроса на слияние (по умолчанию: feat: update translations via @lingodotdev)
LINGODOTDEV_COMMIT_MESSAGE — Пользовательское сообщение коммита (по умолчанию: feat: update translations via @lingodotdev)
LINGODOTDEV_WORKING_DIRECTORY — Запуск интеграции в подкаталоге (по умолчанию: .)
LINGODOTDEV_PROCESS_OWN_COMMITS — Обрабатывать коммиты, сделанные этой интеграцией (по умолчанию: false)

Устранение неполадок

Распространённые ошибки и их решения:

Ошибка	Решение
`remote: HTTP Basic: Access denied`	Добавьте переменную `GL_TOKEN` в настройки CI/CD
`GitbeakerRequestError: Forbidden`	Ваш токен GitLab не имеет области действия `api`