Локалізація через API: рядки, листи та документи — повний цикл

Усе, що ви робите в редакторі, під силу й скрипту: імпорт, переклад різними мовами з вашим глосарієм та пам’яттю перекладів, перевірка й експорт. Цей посібник проведе вас від отримання ключа до готового перекладу, а потім детально розбере кожен етап циклу. Інтерактивний довідник та OpenAPI JSON — це вичерпна технічна специфікація; transept.ai/developers — стисла односторінкова версія цього посібника. Один нюанс у назвах перед першим викликом: для користувача одиницею розрахунку всюди є слова, проте в полях API-відповідей збереглася історична назва credits (estimatedCredits, spendable). Це одна й та сама величина.

Отримання ключа

Налаштування → Розробник у застосунку; скопіюйте секретний ключ (він доступний лише раз). У запитах він передається як Authorization: Bearer tsk_live_… — лише в заголовку, ніколи не в URL.

Доступ за ключами розмежовано: повний доступ або права на читання й запис для окремих розділів (документи, запуски, глосарії, стайл-гайди, пам’ять перекладів, вебхуки, проєкти). Якщо запит виходить за межі дозволів ключа, повертається помилка 403 із зазначенням того, чого бракує. Ключ не може створювати інші ключі — керування ними здійснюється лише в додатку.

Весь цикл за п’ять викликів

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

export KEY="tsk_live_…"
BASE="https://app.transept.ai/api/public/v1"

# 1: who am I, what can this key do, what's the balance?
curl -s $BASE/me -H "Authorization: Bearer $KEY"

# 2: a document plus its target-language fan-out, in one call
curl -s -X POST $BASE/documents \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"title": "Welcome email", "content": "# Welcome\n\nStart your free trial.",
       "content_type": "markdown", "source_language": "en",
       "target_language": "de", "target_languages": ["fr", "uk"]}'
# → { document_id, language_group: [ {id, target_language}, … ] }

# 3: price it (free, no side effects), then run it across every language
curl -s $BASE/workflow-templates -H "Authorization: Bearer $KEY"   # discover ids

curl -s -X POST $BASE/group-runs/estimate \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"document_id": "<master>", "template_id": "end_to_end", "target_languages": "all"}'
# → { lanes: [ {language, estimatedCredits, minCredits} ], totals: {sufficient} }

curl -s -X POST $BASE/group-runs \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: welcome-2026-08-05" \
  -d '{"document_id": "<master>", "template_id": "end_to_end", "target_languages": "all"}'
# → { id: <group_run_id>, runs: [ {job_id, language, block_count} ] }

# 4: wait by polling, or get pushed a signed event instead
curl -s $BASE/group-runs/<group_run_id> -H "Authorization: Bearer $KEY"
# → { status, runs: [ {language, status, progress, gate} ] }

# 5: read the results in the format your pipeline wants
curl -s "$BASE/documents/<version-id>/content?format=markdown" \
  -H "Authorization: Bearer $KEY"

Три корисні звички з першого ж дня: спочатку оцінюйте вартість (це безкоштовно; ви отримуєте діапазон від мінімальної до максимальної суми, причому фактичні витрати ніколи не перевищують цей максимум), надсилайте Idempotency-Key у POST-запитах на створення завдань (повторна спроба просто поверне результат першої замість подвійного списання коштів) та зареєструйте вебхук (POST /webhooks {url, events: ["group_run.completed"]}), щоб не витрачати ресурси на постійне опитування. Сповіщення підписуються за допомогою HMAC, мають систему повторних спроб і журнал доставки.

Три формати вхідних даних

Проза та електронні листи

POST /documents з content_type: "html" зберігає форматування, посилання та плейсхолдери шаблонів під час перекладу; format=html повертає перекладений лист у тому самому вигляді. Або ж можна обійтися без цього запиту: встановіть для тригера воркфлоу значення «тіло запиту є контентом» і спрямуйте свій ESP, Zapier/n8n або CI на URL-адресу тригера:

# the trigger URL (with its secret) comes from the workflow's trigger card;
# the secret IS the auth, so no Authorization header
curl -s -X POST $BASE/hooks/<trigger-secret> \
  -H "Content-Type: application/json" \
  -d '{"content": "<h1>Welcome!</h1><p>Your trial starts today.</p>",
       "content_type": "html",
       "title": "Trial welcome",
       "external_id": "welcome-v4"}'
# → 202 { run id, document_id, created }

# raw bodies work too: POST the markdown/HTML itself with its Content-Type
curl -s -X POST $BASE/hooks/<trigger-secret> \
  -H "Content-Type: text/markdown" \
  --data-binary $'# Welcome\n\nStart your free trial.'

Тригер визначає, чи створювати для кожної доставки новий документ, чи оновлювати один і той самий (під час оновлення система зіставляє вміст, щоб перекладати лише змінені блоки). Повторні доставки дедуплікуються за external_id або хешем вмісту протягом 24 годин. Див. тригери вебхуків.

Файли

POST /documents/upload (multipart) з файлом, а також source_language, target_language, необов’язковим target_languages[] та project_id. Повний цикл роботи з DOCX: під час експорту переклад вбудовується назад у ваш оригінальний файл, тож стилі та верстка зберігаються. CSV, PO та XLIFF імпортуються як одиниці з ключами й експортуються у власному форматі. Деталі форматів і зіставлення стовпців: файли рядків.

Каталоги рядків

Кожен рядок — це окрема одиниця зі стабільним id, полем source, а також необов’язковими параметрами context, max_length та placeholders:

curl -s -X POST $BASE/documents/import-strings \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"document": {
        "format": "transept-strings", "version": 1, "source_locale": "en",
        "target_locales": ["de", "fr", "uk"],
        "metadata": {"name": "App UI"},
        "units": [
          {"id": "app.save", "source": "Save", "context": "Toolbar button"},
          {"id": "app.greeting", "source": "Welcome, {name}", "context": "Dashboard header"}
        ]}}'
# → { processing_job_id }; poll GET /document-jobs/{id}

Контекст надходить до моделі як вказівка для перекладу, ліміт max_length забезпечується механізмом скорочення та повторних спроб, плейсхолдери захищені, а форми множини розгортаються відповідно до правил кожної мови. Вже наявні у файлі переклади безкоштовно стають активними та поповнюють пам’ять перекладів. Якщо цільові мови не вказано, запит відхиляється з помилкою no_target_languages, щоб не імпортувати документ, який не матиме жодного перекладу. Весь робочий цикл описано в розділі Локалізація каталогу рядків через API.

Один шаблон листа, три мови

Розглянемо конкретний приклад із листом. Liquid залишається незмінним під час перекладу:

# the template body goes in as HTML; three target languages fan out
curl -s -X POST $BASE/documents \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"title": "Trial welcome", "content_type": "html", "source_language": "en",
       "target_languages": ["de", "fr", "uk"],
       "content": "<h1>Welcome, {{ first_name | default:\"friend\" }}!</h1><p>Your trial starts today.</p>"}'

{{ first_name | … }} маскується перед обробкою моделлю та відновлюється дослівно. Є один виняток: фолбек friend — це текст, призначений для читача, тому він ПЕРЕКЛАДАЄТЬСЯ, тоді як сам тег — ні. Виконайте груповий запуск, як у посібнику зі швидкого старту, а потім зчитайте результат для кожної мови:

curl -s "$BASE/documents/<de-version-id>/content?format=html" \
  -H "Authorization: Bearer $KEY"
# → the same HTML with German copy, Liquid intact; paste it into the ESP's de variant

Варіант без ручного втручання: тригер вебхуку отримує шаблон безпосередньо від ESP, воркфлоу запускається одразу після отримання, а вебхук group_run.completed повертає перекладений HTML. Особливості конкретних платформ (теги Braze, умови Mailchimp): шаблони листів ESP та посібник із локалізації електронної пошти.

Глосарії, стайлгайди, пам’ять перекладів

Створіть глосарій, наповнивши його термінами в тому ж запиті:

curl -s -X POST $BASE/glossaries \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"name": "Product terms", "source_language": "en",
       "terms": [{"source_term": "Transept", "target_term": "Transept",
                  "do_not_translate": true}]}'

Доповніть наявний (запит GET /glossaries покаже всі доступні для вашого ключа):

curl -s -X POST $BASE/glossaries/<id>/terms/bulk \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"terms": [
        {"source_term": "workspace", "target_term": "Arbeitsbereich"},
        {"source_term": "run", "target_term": "Lauf", "notes": "the noun: a workflow execution"}
      ]}'

Або ж згенеруйте їх на основі документа, якому довіряєте: для цього є POST /glossaries/{id}/auto-build та POST /styleguides/generate, кожен із безкоштовним аналогом …/estimate. Обидва методи тарифікуються за кількістю слів і вимагають auto_apply: true через API. Оскільки робота без інтерфейсу не передбачає етапу перевірки, результат фіксується одразу після завершення. Відстежуйте статус через GET /generation-jobs/{id}. Альтернатива з перевіркою в додатку: створення на основі документа. Підключіть їх один раз — і вони застосовуватимуться під час кожного наступного запуску через API, MCP чи редактор без жодних додаткових витрат:

curl -s -X PATCH $BASE/documents/<id>/translation-settings \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"glossary_ids": ["<glossary_id>"], "styleguide_version_ids": ["<active_version_id>"]}'

Стайлгайди підключаються за допомогою ID активної версії (отриманого через GET /styleguides/{id}); [] відключає їх. Обидва параметри також працюють у запиті POST /documents під час створення документа. В інтерфейсі: глосарії, стайлгайди. Пам’ять перекладів не потрібно підключати окремо: кожен завершений переклад автоматично індексується та використовується повторно. Робіть у ній запити (POST /translation-memory/query, безкоштовно), наповнюйте її з файлів TMX/XLIFF (POST /translation-memory/import, безкоштовно) або експортуйте всі дані (GET /translation-memory/export-tmx). Див. пам’ять перекладів та імпорт існуючих перекладів.

Команди

Командний ключ використовує спільний баланс команди та успадковує її проєкти, глосарії, стайлгайди й пам’ять перекладів. Щоб створити документ у межах команди, передайте project_id командного проєкту (їх можна отримати через GET /projects; командні проєкти мають поле team_id). В усьому іншому робота ідентична до особистого використання. Команди та проєкти налаштовуються в додатку: проєкти, команди та запрошення.

Запуски та етапи перевірки

POST /runs обробляє одну мовну версію, тоді як POST /group-runs охоплює всі цільові мови одночасно, створюючи за потреби відсутні версії. Обидва запити мають безкоштовний режим оцінки, приймають Idempotency-Key та підтримують скасування. Крок воркфлоу, налаштований на очікування перевірки, призупиняє запуск: GET /runs/{id} повідомляє про gate_pending: true разом зі зведенням результатів перевірки. З боку користувача за цю паузу відповідають панель перевірки та керована перевірка; з боку скрипта:

# continue downstream steps (all blocks, or a reviewed subset):
curl -s -X POST $BASE/runs/<id>/gate/approve \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"approved_block_ids": ["…"]}'    # omit the field to approve all

# a gate with nothing downstream is dismissed instead:
curl -s -X POST $BASE/runs/<id>/gate/acknowledge -H "Authorization: Bearer $KEY"

Етап перевірки ніколи не минає сам собою: його потрібно схвалити — чи то за допомогою скрипта, чи асистента через MCP, чи вручну в додатку. Спеціального прапорця для попереднього схвалення етапів під час запуску не існує; якщо процес не має зупинятися взагалі, використовуйте воркфлоу без кроку перевірки.

Формати виводу

GET /documents/{id}/content?format=<f> за ID мовної версії:

format=strings для основного документа повертає всі мови одним викликом, уже готовими до коміту.

Оновлення лише змін

Для каталогів рядків повторно надішліть увесь поточний файл; сервер сам обчислить різницю:

# 1: re-import the complete current corpus; Transept diffs it by unit id
curl -s -X POST $BASE/documents/<master>/import-strings \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d @app-ui.tstrings.json > delta.json
# → { units: {added, changed, unchanged, removed}, delta_block_ids: {<doc_id>: [block ids]} }

# 2: feed delta_block_ids VERBATIM into a group run; only those blocks translate
jq -n --slurpfile d delta.json \
  '{document_id: $d[0].master_document_id, template_id: "end_to_end",
    target_languages: "all", block_ids: $d[0].delta_block_ids}' \
| curl -s -X POST $BASE/group-runs \
    -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" --data-binary @-

Незмінні рядки зберігають переклад і статус перевірки, а виправлення одного рядка коштує як один рядок. (Щоб опрацювати лише зміни в межах того самого виклику, передайте run: {template_id} безпосередньо під час повторного імпорту.) Це програмна реалізація функції Запускати лише для зміненого вмісту. Для текстових документів зі зміненим оригіналом запит POST /documents/{id}/resync-source заново зіставляє блоки: незмінні блоки зберігають переклад, змінені — стають застарілими, а запуск лише оновленого вмісту зачіпає тільки їх. Оскільки повторна синхронізація заново аналізує збережений файл оригіналу, редагуйте джерела через шлях імпорту, а не виправляючи окремі блоки.

ШІ-асистенти (MCP)

Тут діє той самий цикл, що й для інструментів агентів, за адресою https://app.transept.ai/api/public/v1/mcp: me_get → document_create → group_run_estimate / group_run_start → group_run_get → document_content_get. Підключення відбувається через OAuth (авторизація в браузері, без ручного копіювання ключів; для headless-режиму підійде Bearer-токен). Інструменти працюють суворо в межах наданих дозволів, а будь-яка операція з витратою слів спочатку повертає попередню оцінку; асистент має надати явне підтвердження. Налаштування для клієнта: Підключіть свого ШІ-асистента.

Часті запитання

Чи списуються слова за оцінку, повторний імпорт або імпортовані переклади?

Ні. Оцінка вартості безкоштовна й не має побічних ефектів. Повторний імпорт каталогу також нічого не коштує (різниця обчислюється на сервері), а переклади, які вже містяться у ваших файлах, додаються як готова робота без жодних списань. Слова витрачаються лише тоді, коли Transept перекладає щось для вас. Попередня оцінка за верхньою межею згодом коригується відповідно до фактичних витрат, а невикористаний резерв повертається.

Чи може автоматизація оминати мої етапи перевірки?

To improve the editorial flow and narrative style, I have refined the sentence structures to be more active and less reliant on conditional "if/then" patterns. I also adjusted the terminology to better reflect the technical intent while maintaining consistency with the previously established context.

Чи доступний API у безкоштовному тарифі?

Так. API-ключі доступні в усіх тарифних планах, зокрема й у безкоштовному; жодних додаткових бар’єрів для доступу немає. Обсяг використання залежить лише від вашого балансу слів — так само як і в редакторі. Щомісячний ліміт слів у плані Free поширюється на API так само, як і на решту функцій.

Як локалізувати шаблони листів без ручного експорту?

Спрямуйте дані з вашої поштової платформи на вебхук-тригер: тіло шаблону з POST-запиту стає документом, воркфлоу його перекладає, а під час експорту ви отримуєте ту саму структуру HTML із уже вбудованим перекладом. Плейсхолдери та синтаксис шаблонів залишаються недоторканими протягом усього циклу обробки. Технічні нюанси для конкретних сервісів описані в посібнику з локалізації імейлів.

Де знайти повний довідник ендпоінтів?

Інтерактивний довідник Swagger базується на тій самій специфікації OpenAPI, яку можна імпортувати в n8n, Zapier або генератор коду (вихідний JSON). Цей посібник — це змістовний вступ, а специфікація — технічний контракт.