Архитектура

Как Тетива переводит файл за восемь шагов

Без чёрного ящика. Каждый шаг — отдельный модуль, который можно проверить, переопределить, заменить на свой.

локально · твой ноутбук tetiva push HTTPS бэкенд · Yandex Cloud РФ парсер формата JSON · ARB · XML · .strings дельта new · changed · removed контекст glossary · TM · brand voice LLM-роутер pair → provider Claude GPT Qwen YandexGPT / GigaChat валидаторы placeholders · plural · ICU GitHub · твой репо pull request + CI green check
Поток

От локального файла до зелёного CI

  1. CLI читает локальный файл

    $ tetiva push --source ./locales/en.json --targets kk,uz,tr,ar

    CLI определяет формат файла по расширению и сигнатуре содержимого: .json с i18next-структурой, .json с ICU MessageFormat, .strings (Apple), .stringsdict, Android strings.xml, Flutter .arb, Java .properties. Для каждого формата используется свой парсер — не regex, а полноценный AST-разбор. Ключи извлекаются с сохранением иерархии, плейсхолдеры распознаются и нормализуются во внутреннее представление.

  2. Сравнение с предыдущим состоянием

    CLI читает локальный .tetiva/state.json — снимок ключей с последнего успешного push'а. Сравнение даёт три множества: новые ключи, изменённые ключи, удалённые ключи. На сервер уходят только эти три множества, не весь файл. Это ускоряет инкрементальные пуши и снижает расход LLM-токенов.

  3. Передача на бэкенд

    CLI отправляет дельту на API в Yandex Cloud (для облачного тира) или на твой self-hosted appliance (для on-premise). Авторизация — по API-ключу проекта; ключ хранится в .tetiva/auth или в системном keychain. Передача — HTTPS с pinned-сертификатом для appliance-инстанций.

  4. Подготовка контекста

    Для каждого ключа бэкенд собирает контекст: значение глоссария для терминов из ключа, похожие ранее переведённые строки из translation memory, brand-voice prompt проекта, локаль-специфичные требования (RTL, BCP 47 script-вариант, CLDR plural-категории), путь файла как косвенный контекст (auth/login.json → «это про логин»). Это retrieval-augmented localization — описана подробнее ниже.

  5. Маршрутизация в LLM

    Роутер выбирает провайдера и модель по таблице. Языковая пара EN↔RU → Claude или GPT. RU↔KZ / UZ / TR / AR / FA / ZH → Qwen primary, Claude fallback. Residency-чувствительный тариф → YandexGPT или GigaChat. Тир с собственным ключом → провайдер покупателя. Полная таблица маршрутизации — на странице /models.

  6. Структурная валидация

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

    [validators]
    ├── PlaceholderValidator — все плейсхолдеры исходника сохранены
    ├── ICUMessageFormatValidator — структура plural / select валидна
    ├── PluralCategoryValidator — все CLDR-категории целевой локали присутствуют
    ├── HTMLBalanceValidator — открытые теги соответствуют закрытым
    ├── MarkdownBalanceValidator — **, _, []() сбалансированы
    ├── LengthBudgetValidator — длина не превышает заявленный бюджет UI
    ├── EncodingValidator — UTF-8 валиден, BOM соответствует формату
    └── LocaleTagValidator — все locale-теги в каноническом BCP 47

    Если валидация падает — перевод отправляется на повторную генерацию с явной инструкцией исправить найденную ошибку. Если повтор тоже падает — ключ помечается флагом needs-review и попадает в PR с пометкой.

  7. Запись результата и обновление TM

    Прошедшие валидацию переводы записываются в translation memory проекта на стороне сервера, отдаются обратно CLI в виде патча для целевых файлов локалей.

  8. Открытие PR (или коммит в текущую ветку)

    CLI создаёт коммит на текущей ветке либо открывает новую ветку и PR через GitHub API. Имя ветки — tetiva/<hash> или то, что задано в конфиге. PR содержит diff по файлам локалей и markdown-таблицу со сводкой: сколько новых ключей переведено на каждую локаль, сколько помечено needs-review, какие LLM использовались.

Контекст

Контекст, а не голая модель

Машинный перевод без контекста — это перевод одной фразы из словаря. LLM без контекста делает то же самое, только дороже. Разница в качестве на UX-копии возникает, когда модель видит не только исходную строку, но и:

Glossary

Глоссарий проекта

Твои бренд-термины, продуктовые имена, аббревиатуры, которые должны переводиться единообразно. Если ты сказал, что «tier» в нашем продукте — это «тариф», а не «уровень» — глоссарий обеспечивает, что во всех тысячах ключей будет именно «тариф».

Translation memory

Похожие переводы

Ранее переведённые похожие строки. Если у тебя уже есть «Сохранить изменения» → «Өзгерістерді сақтау», и в новой строке «Сохранить» — TM передаёт это как пример «вот как мы переводим Сохранить в этом проекте».

File path

Путь файла как контекст

checkout/discount.json → «это про оформление заказа и скидку», errors/network.json → «это про сетевые ошибки». Спасает от классической ошибки «Save 20%» → «Сохрани 20%» вместо «Сэкономь 20%».

Brand voice

Стиль и регистр

Твой собственный prompt с описанием стиля: «обращайся на ты», «не используй восклицательные знаки», «технический регистр», «не сокращай слова в push-нотификациях».

CLDR

Локаль-специфика

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

Prompt

Результат

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

Интерфейсы

Чем Тетива говорит с твоим стеком

CLI @tetiva/cliОсновной интерфейс. Установка через npm, pip, brew, cargo. Команды: init, push, pull, status, benchmark, glossary, tm.
GitHub Actiontetiva/action@v1. Триггерится на push в любую ветку, открывает PR с переведёнными локалями.
GitLab CIOfficial template в registry.
VS Code extensionInline-подсветка непереведённых ключей, hover с переводом из TM, command palette для запуска CLI.
JetBrains pluginТо же для IntelliJ, WebStorm, PyCharm, Android Studio.
MCP serverДля Claude Code, Cursor, Codex. Позволяет AI-агенту читать и редактировать переводы напрямую.
REST APIДля всего, что не покрывается выше. OpenAPI-спецификация — на /docs/api.
WebhooksУведомления о завершении перевода, о флагах needs-review, об изменениях глоссария.
Границы продукта

Чего в продукте нет

Это не CAT-инструмент для переводчиков. В Тетиве нет редактора с подсветкой fuzzy matches, нет встроенной системы заданий для команды переводчиков, нет почасовой оплаты подрядчиков. Если у тебя выстроенный процесс работы с переводческими агентствами на десятки тысяч слов в месяц — Smartcat или Crowdin закрывают эту задачу полнее.

Это не маркетплейс переводчиков. Мы не сводим тебя с фрилансерами и не берём комиссию с их оплаты. Если нужна редактура носителем — нанимай отдельно, мы даём API для приёма правок обратно.

Это не дизайн-инструмент. Нет Figma-плагина с in-context переводом макетов в v1. Это в roadmap на следующий релиз.

Это не система управления документами. Тетива работает с UI-строками. Длинные маркетинговые тексты, юридические документы, статьи в блог — для них нужен другой инструмент с другой моделью контекста.

Архитектура — не магия

Каждый шаг описан, каждый модуль можно проверить. Если что-то непонятно — открывай issue в публичном репозитории CLI или пиши на engineering@tetiva.dev.

Установить CLI Документация API