Назад в блог

Обновление переводов по воздуху (OTA) без редеплоя

Обновление переводов по воздуху (OTA) без редеплоя

Неверный термин или обрезанная подпись обычно обнаруживаются, когда сборка уже выпущена. Если переводы вшиты в сервис, исправление одной строки означает новую сборку и деплой. Обновление переводов по воздуху (OTA) убирает этот шаг. Ownlate замораживает утверждённые переводы в версионированный релиз и отдаёт его по HTTP за ключом доступа, а клиенты для Go, Rust и NestJS подхватывают каждую новую версию, пока сервис продолжает работать.

Релиз — снимок утверждённых переводов

Экспорт — это файл, который вы коммитите. Релиз — снимок, который скачивает ваше приложение.

Создаётся он со вкладки Релизы проекта или мутацией GraphQL createRelease. Релиз берёт утверждённые переводы проекта в том виде, в каком они есть в этот момент, и замораживает их. Всё, что ещё не утверждено, в него не попадает.

Несколько свойств, которые стоит знать:

  • Версия присваивается автоматически и растёт в пределах проекта. Название и описание добавляете вы, чтобы сказать, что изменилось.
  • Незаконченный язык релиз не блокирует. Он попадает в релиз с утверждёнными ключами и без остальных, поэтому перед выпуском релиза проверьте прогресс.
  • Множественное число сохраняется целиком. Сегмент с формами множественного числа несёт весь набор форм как значение.
  • Форм бандла две. По умолчанию бандл — плоское отображение ключа в значение, по отображению на язык. С splitByFiles ключи сгруппированы по файлу, из которого пришли, — это подходит приложению, которое грузит по одному пространству имён за раз.

Как OTA-обновления переводов попадают в работающий сервис

У каждого проекта одна раздача: постоянный ключ доступа, который отдаёт его релизы по HTTP без авторизации. Она находится в разделе Релизы → Раздача, и к ней привязаны три публичные ручки:

GET https://api.ownlate.com/public/v1/ota/{accessKey}/manifest
GET https://api.ownlate.com/public/v1/ota/{accessKey}/bundles
GET https://api.ownlate.com/public/v1/ota/{accessKey}/bundles/{language}

Манифест маленький, его дёшево опрашивать:

API=https://api.ownlate.com/public/v1
curl $API/ota/$ACCESS_KEY/manifest
{ "version": 14, "languages": ["de", "sr", "hu"], "publishedAt": "2026-09-18T09:12:44Z" }

Все три ручки по умолчанию отдают последний релиз. Добавьте ?version=5, чтобы закрепиться на более раннем, — это выручает, когда старая сборка ждёт ключи, которых в текущем релизе уже нет.

Путь от исправленной строки до продакшена выглядит так:

  1. Переводчик исправляет строку, и её утверждают.
  2. Кто-то создаёт новый релиз, и версия увеличивается на единицу.
  3. При следующем фоновом обновлении рантайм-клиенты загружают новый бандл и подменяют им старый.

Ни сборки, ни деплоя не нужно.

Быстрый старт на Go

Установите модуль:

go get github.com/OwnLate/go-client

Создайте клиент, нацеленный на OTA-бандл, запустите фоновое обновление и дождитесь первой успешной загрузки:

client, err := ownlate.New(ownlate.Config{
    Source: ownlate.OTASource{Bundles: []ownlate.OTABundle{{AccessKey: accessKey}}},
    Locale: "ru",
})
if err != nil {
    return err
}
defer client.Close()

client.Start(ctx) // обновление в фоне каждые пять минут
<-client.Ready()  // первая успешная загрузка

client.T("notification.title", "en_US")
client.Translate("emails", "greeting", map[string]any{"name": "Roman"}, "ru")

Если загрузка не удалась, Start пишет ошибку в лог и повторяет попытку. Если фоновое обновление не нужно, одиночный вызов client.Load(ctx) заменяет Start и вместо этого возвращает ошибку загрузки.

Бандл без Prefix попадает в пространство имён __ota__ (константа ownlate.OTANamespace), и client.T(key, locale) — сокращение как раз для этого случая. Чтобы разделить несколько бандлов, дайте каждому префикс — он станет его пространством имён:

ownlate.OTASource{Bundles: []ownlate.OTABundle{
    {AccessKey: emailsKey, Prefix: "emails"},
    {AccessKey: pushKey, Prefix: "push"},
}}

Бандлы с общим префиксом сливаются в одно пространство имён, а при конфликте ключей побеждает последний.

Период обновления задаёт поле PollInterval в Config, по умолчанию пять минут, а RetryInterval — пауза после неудачной загрузки. Клиент безопасен для конкурентного использования: Translate читает снимок под RWMutex, а обновление заменяет этот снимок целиком.

Rust

[dependencies]
ownlate = { git = "https://github.com/OwnLate/rust-client" }
let client = ownlate::Client::ota(access_key, "en_US")?;

let refresh = client.start(); // обновление в фоне каждые пять минут
client.ready().await;         // первая успешная загрузка

client.t("notification.title", "en_US");
client.translate("emails", "subject", Some(&json!({ "plan": "Pro" })), "en_US");

Client дёшево клонируется: все клоны разделяют одни переводы и одну задачу обновления. Если дропнуть RefreshHandle, который вернул start, обновление остановится. Как и в Go, client.load().await? выполняет одну загрузку и возвращает ошибку, а о неудачных загрузках сообщается через tracing.

NestJS

npm install @globalart/ownlate-nestjs-translator

Модуль оборачивает то же поведение для приложения на Nest: загружает бандл при старте и обновляет его в фоне. Клиент для Go — порт этого пакета, а правила разрешения ключей, описанные ниже, у клиентов общие.

Как разрешаются отсутствующие ключи и локали

Бандл может отставать от кода. Новый ключ может выйти раньше, чем утвердят его перевод, а какую-то локаль могут не перевести вовсе. Клиенты разрешают каждый поиск в фиксированном порядке, чтобы такие пробелы оставались безобидными:

  1. Локаль берётся из вызова, иначе из Config.Locale.
  2. Ищется пространство имён. Для OTA-источника неизвестное пространство сводится к __ota__.
  3. Если запрошенной локали нет, берётся локаль того же языка: en_US дотягивается до en и обратно. Если не вышло и так, берётся первая по алфавиту локаль, чтобы выбор не прыгал от вызова к вызову.
  4. Неизвестный ключ возвращается как есть, поэтому отсутствующий перевод никогда не оставляет после себя пустую строку.
  5. Подстановки вида {{name}} заменяются переданными значениями.

Клиент для Rust добавляет ещё один шаг, прежде чем сдаться: ищет ключ в остальных локалях, поэтому перевод, который в одном языке ещё на проверке, не показывается голым ключом. Кроме того, у него есть Client::get, который читает ключ ровно в том виде, в каком он хранится, — без подмены локали и без возврата самого ключа.

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

Свой клиент: манифест, ETag и 304

OTA-ручкам не нужны учётные данные, поэтому читать их может любой HTTP-клиент. Ответы несут ETag, собранный из версии релиза и времени публикации. Пришлите его обратно в If-None-Match — и неизменившийся бандл ответит 304 Not Modified без тела:

curl -i --compressed $API/ota/$ACCESS_KEY/bundles/de
# запомните заголовок ответа ETag, затем:
curl -i --compressed -H "If-None-Match: $ETAG" $API/ota/$ACCESS_KEY/bundles/de
# 304 Not Modified, пустое тело, пока релиз не изменился

Бандлы сжимаются, если клиент сообщил, что принимает сжатие, и сжатая форма тоже кешируется. Бандл одного языка выглядит так:

{
  "version": 14,
  "language": "de",
  "splitByFiles": false,
  "publishedAt": "2026-09-18T09:12:44Z",
  "translations": { "home.title": "Hallo" }
}

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

OTA или pull request

OTA подходит лучше, когда:

  • тексты меняются чаще кода и ждать следующего деплоя ради исправления строки нельзя;
  • одни и те же строки читают несколько сервисов, и один релиз должен обновить их все;
  • контент опирается на формы множественного числа, а бандл сохраняет весь набор форм.

Коммит выгруженных файлов через pull request подходит лучше, когда:

  • переводы нужно ревьюить рядом с кодом и версионировать вместе с ним в Git;
  • сервис не должен зависеть от HTTP-запроса в рантайме, чтобы получить свои строки;
  • строки не предназначены для чтения кем-либо за пределами вашего продукта.

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

И ещё одно различие. Браузерный SDK и расширение Chrome — не то же самое, что эти рантайм-клиенты. Они позволяют переводчику править строки прямо в работающем продукте, а такие правки ложатся черновиками, которые всё равно проходят проверку.

Что почитать дальше