Локалізація каталогу рядків через API

Формат Transept із ключами — це .tstrings.json: список елементів, кожен з яких має стабільний id, source та, за бажанням, context (що це за рядок і де він з’являється), max_length і placeholders. ID — це свого роду контракт: завдяки йому переклади зберігають свою цілісність під час повторного імпорту, статус перевірки не втрачається, а експорт усіх мов прив’язується до ключів. Обидва додаткові параметри мають практичне значення: контекст надає моделі вказівки для перекладу, а обмеження символів забезпечує автоматичне скорочення тексту та повторну спробу.

Файли CSV, gettext PO та XLIFF імпортуються як такі самі елементи з ключами через інтерфейс застосунку або ендпоінт завантаження; див. файли рядків, щоб дізнатися про відповідність кожного з форматів. Ця стаття присвячена керуванню цим циклом через код, де .tstrings.json є основним форматом.

Виконайте POST /documents/import-strings, передавши каталог у форматі JSON. Цільові мови визначаються в чіткому порядку: пріоритет мають параметри target_language / target_languages, явно вказані в запиті; якщо їх немає — target_locales із заголовка каталогу; інакше виклик одразу завершиться помилкою no_target_languages, замість того щоб імпортувати документ без цільових мов. Запит повертає processing_job_id; опитуйте GET /document-jobs/{id}, доки імпорт не завершиться і ви не отримаєте ID документів.

Переклади, які вже містяться у файлі (targets: {de: "…"}), стають активними перекладами для відповідних рядків. Це безкоштовно й не потребує запуску перекладу; вони одразу поповнюють вашу пам'ять перекладів. Це працює так само, як і імпорт наявних перекладів через інтерфейс застосунку.

# BASE="https://app.transept.ai/api/public/v1"; KEY from Settings → Developer
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}

Надішліть весь поточний каталог повторно через POST /documents/{id}/import-strings, а не лише скорочену версію. Сервер порівняє його за ID елементів і поверне результат (added, changed, unchanged, removed), а також delta_block_ids — список блоків, які потребують перекладу для кожної мови. Передайте цей об'єкт без змін як параметр block_ids для групового запуску, і система перекладе лише ці блоки. Ви також можете передати параметр run безпосередньо під час повторного імпорту, щоб запустити переклад оновлень тим самим запитом.

Незмінені елементи зберігають свої переклади та результати вже виконаної перевірки; це реалізація принципу Запускати лише змінене на рівні API. Виправлення одного рядка в каталозі із сотень інших коштує як один рядок.

# 1. Re-submit the whole current catalog; the server 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
# → { 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
curl -s -X POST $BASE/group-runs \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"document_id": "<master>", "template_id": "end_to_end",
       "target_languages": "all", "block_ids": { "<doc_id>": ["<block id>", "…"] }}'

Запит GET /documents/{id}/content?format=strings до основного документа повертає один файл .tstrings.json із перекладами всіма мовами, прив'язаними до ID елементів: один запит — і результат готовий до коміту або інтеграції у ваш білд. Цей самий ендпоінт дозволяє отримати версії для окремих мов (markdown, html, csv, xliff, tmx), якщо для вашого конвеєра потрібен специфічний формат передачі даних; повну таблицю наведено в розділі Автоматизація Transept через API.

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

curl -s "$BASE/documents/<master>/content?format=strings" \
  -H "Authorization: Bearer $KEY"
# → one .tstrings.json with every language keyed by unit id