Интеграции

Интеграция связывает проект — или всё рабочее пространство — с чем-то за пределами Ownlate. Каждая состоит из провайдера, настроек и учётных данных, которые шифруются перед сохранением и никогда не возвращаются из API.

Категория	Провайдеры
Система контроля версий	GitHub, GitLab
Машинный перевод	OpenAI, Anthropic, Mistral, DeepL, Google, Azure — см. ИИ-перевод
Уведомления	Slack, Microsoft Teams, Discord, Mattermost, Matrix, Telegram
Вебхуки	Обычный вебхук

Управление интеграцией

Интеграции живут на вкладке Интеграции проекта, а общие для пространства — в разделе Рабочее пространство → Интеграции.

Действие	Что делает
Проверить до сохранения	Проверяет введённые учётные данные, не сохраняя их
Проверить	Проверяет сохранённую интеграцию
Приостановить	Сохраняет настройки, но останавливает работу
Включить	Возвращает приостановленную в строй
Журналы синхронизации	Запись каждого запуска построчно с результатом

Область определяет охват. Интеграция с областью project обслуживает один проект, с областью workspace — доступна всем проектам пространства. Для машинного перевода проект без собственной интеграции берёт интеграцию пространства. Для вебхуков хуки уровня пространства срабатывают, только если у проекта нет своего. Уведомления отправляются из интеграций уровня проекта.

Всё, что интеграция делает, попадает в её журнал синхронизации, включая неудачи, — поэтому вебхук, который не дошёл, отличим от вебхука, который не отправляли.

Git: GitHub и GitLab

Интеграция с системой контроля версий принимает адрес репозитория, ветку (по умолчанию main) и токен доступа.

Синхронизация

При синхронизации Ownlate читает ownlate.yml — или ownlate.yaml — из корня ветки. Это тот же файл, которым пользуется CLI:

project_id: 00000000-0000-0000-0000-000000000000

files:
  - source: locales/en.json
    translation: locales/{lang}.json

Для каждого сопоставления Ownlate забирает исходный файл из репозитория и загружает его, создавая и обновляя сегменты ровно так же, как это сделала бы ручная загрузка. Файл, указанный в конфигурации, но отсутствующий в репозитории, пропускается с записью в журнале; репозиторий без конфигурации ничего не синхронизирует и прямо об этом пишет.

В files[].translation обязательно должен быть placeholder {lang} — это шаблон, по которому переведённые файлы записываются обратно.

Синхронизация идёт в фоне. Запустить её вручную можно со вкладки интеграций либо через API: PATCH /v1/workspaces/{workspaceId}/integrations/{id}/sync.

Pull request’ы

Создать PR работает в обратную сторону: Ownlate выгружает утверждённые переводы для выбранных языков, раскладывает их по путям из ownlate.yml, отправляет новую ветку и открывает pull request — на GitLab это merge request. В ответе приходит адрес, поэтому его может подхватить пайплайн.

Токену нужны права читать репозиторий, отправлять ветку и открывать pull request.

Уведомления

Шесть адресатов в чатах, каждый — в стиле своей платформы: сообщение Block Kit в Slack, MessageCard в Teams и так далее.

Провайдер	Что требуется
Slack	Incoming webhook URL
Microsoft Teams	Connector URL
Discord	Webhook URL
Mattermost	Webhook URL
Telegram	Токен бота, идентификатор чата
Matrix	Адрес homeserver, идентификатор комнаты, токен доступа

В сообщении — ключ, язык, исходный текст и новый перевод, плюс ссылка прямо на сегмент в Ownlate.

Вебхуки

Интеграция-вебхук принимает адрес и необязательный секрет и отправляет на него JSON:

{
  "event": "translation.approved",
  "payload": {
    "segmentId": "…",
    "projectId": "…",
    "workspaceId": "…",
    "language": "de",
    "key": "home.title",
    "sourceText": "Hello",
    "translationText": "Hallo",
    "actorId": "…",
    "authorId": "…",
    "approvedAt": "2026-08-20T09:31:00Z"
  },
  "timestamp": "1787654321000"
}

Каждая доставка несёт заголовки:

Заголовок	Содержимое
`X-Ownlate-Event`	Имя события
`X-Ownlate-Timestamp`	Миллисекунды с начала эпохи, то же значение, что и в теле
`X-Ownlate-Signature`	`sha256=…`, есть только если задан секрет

Проверка подписи

Подпись — это HMAC-SHA256 от метки времени, точки и сырого тела запроса, на ключе-секрете:

const expected = 'sha256=' + crypto
  .createHmac('sha256', secret)
  .update(`${req.headers['x-ownlate-timestamp']}.${rawBody}`)
  .digest('hex')

Сравнивайте с X-Ownlate-Signature за постоянное время и отвергайте метку времени, слишком старую, чтобы быть настоящей.

События

Уведомления и вебхуки реагируют на следующее:

Событие	Когда
`translation.submitted`	Перевод отправлен на проверку
`translation.reviewed`	Проверяющий пометил перевод проверенным
`translation.approved`	Перевод утверждён
`translation.rejected`	Перевод отклонён
`segment.created`	В проект добавлен новый сегмент

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