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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Добавьте токен доступа Bitbucket (для режима Pull Request)

Если вы планируете использовать режим pull request'ов, создайте токен доступа:

Перейдите в Настройки репозитория → Токены доступа → Создать токен доступа к репозиторию
Предоставьте следующие права:
- Чтение и запись репозиториев
- Чтение и запись pull request'ов
Добавьте токен как переменную репозитория:
- Имя переменной: BB_TOKEN
- Значение переменной: ваш токен доступа Bitbucket

Шаг 2. Создайте рабочий процесс

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

script:
  - pipe: lingodotdev/lingo.dev:main

Эта конфигурация использует pipe Lingo.dev и автоматически запускает движок перевода.

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

Bitbucket Pipelines требует доступ к переменным репозитория и операциям с git:

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

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

Для режима Pull Request:

BB_TOKEN — требуется для создания и управления pull request'ами

Области действия токена доступа (при использовании режима pull request):

Чтение и запись репозиториев — доступ и изменение содержимого репозитория
Чтение и запись pull request'ов — создание и управление pull request'ами

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

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

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

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

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

script:
  - pipe: lingodotdev/lingo.dev:main

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

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

Режим Pull Request

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

script:
  - pipe: lingodotdev/lingo.dev:main
    variables:
      LINGODOTDEV_PULL_REQUEST: "true"

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

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

Требования к токену доступа: Ваш BB_TOKEN должен включать разрешения на чтение и запись как для репозиториев, так и для pull request'ов.

Примечание: Переменная BB_TOKEN обязательна при использовании режима pull request.

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

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

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

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

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

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

image:
  name: atlassian/default-image:2

pipelines:
  branches:
    feat/*:
      - step:
          name: Run i18n
          script:
            - pipe: lingodotdev/lingo.dev:main

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

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

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

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

image:
  name: atlassian/default-image:2

pipelines:
  branches:
    feat/*:
      - step:
          name: Run i18n
          script:
            - pipe: lingodotdev/lingo.dev:main
              variables:
                LINGODOTDEV_API_KEY: "${MY_LINGODOTDEV_API_KEY}" # или OPENAI_API_KEY/ANTHROPIC_API_KEY
                BB_TOKEN: "${MY_ACCESS_TOKEN}"
                LINGODOTDEV_PULL_REQUEST: "true"
                LINGODOTDEV_PULL_REQUEST_TITLE: "feat: update translations"
                LINGODOTDEV_COMMIT_MESSAGE: "feat: update translations"
                LINGODOTDEV_WORKING_DIRECTORY: "apps/web"
                LINGODOTDEV_PROCESS_OWN_COMMITS: "true"

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

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

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

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

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

image:
  name: atlassian/default-image:2

pipelines:
  branches:
    feat/*:
      - step:
          name: Run i18n
          script:
            - pipe: lingodotdev/lingo.dev:main
              variables:
                LINGODOTDEV_API_KEY: "${MY_LINGODOTDEV_API_KEY}"
                BB_TOKEN: "${MY_ACCESS_TOKEN}"
                LINGODOTDEV_PULL_REQUEST: "true"
                LINGODOTDEV_PULL_REQUEST_TITLE: "feat: update translations"
                LINGODOTDEV_COMMIT_MESSAGE: "feat: update translations"
                LINGODOTDEV_WORKING_DIRECTORY: "apps/web"
                LINGODOTDEV_PROCESS_OWN_COMMITS: "true"

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

image:
  name: atlassian/default-image:2

pipelines:
  branches:
    feat/*:
      - step:
          name: Run i18n
          script:
            - pipe: lingodotdev/lingo.dev:main
              variables:
                OPENAI_API_KEY: "${MY_OPENAI_API_KEY}" # или ANTHROPIC_API_KEY
                BB_TOKEN: "${MY_ACCESS_TOKEN}"
                LINGODOTDEV_PULL_REQUEST: "true"
                LINGODOTDEV_PULL_REQUEST_TITLE: "feat: update translations"
                LINGODOTDEV_COMMIT_MESSAGE: "feat: update translations"
                LINGODOTDEV_WORKING_DIRECTORY: "apps/web"
                LINGODOTDEV_PROCESS_OWN_COMMITS: "true"

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

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)
BB_TOKEN — Токен доступа Bitbucket (требуется для режима запроса на слияние)