Lokalizace katalogu řetězců přes API

Formát služby Transept založený na klíčích je .tstrings.json: seznam jednotek, z nichž každá má stabilní id, source a volitelně také context (o jaký řetězec jde a kde se zobrazuje), max_length a placeholders. ID je základem celého mechanismu: díky němu si překlady zachovávají svou identitu i při opakovaných importech, zajišťuje zachování stavu revize a export podle něj klíčuje všechny jazykové verze. Obě doplňující pole mají v praxi důležitou roli: context slouží modelu jako vodítko při překladu a limit znaků je vynucován automatickým zkrácením a novým pokusem o překlad.

Soubory CSV, gettext PO a XLIFF se přes aplikaci nebo nahrávací endpoint importují jako stejné jednotky s klíči; informace o tom, jak se jednotlivé formáty mapují, najdete v sekci soubory s řetězci. Tento článek se věnuje řízení celého cyklu přímo z kódu, ve kterém je .tstrings.json nativním formátem.

Odešlete POST /documents/import-strings s katalogem ve formátu JSON. Cílové jazyky se určují v pevném pořadí: přednost má explicitní parametr target_language / target_languages v požadavku, jinak se použije target_locales z hlavičky katalogu. Pokud není určen žádný jazyk, volání okamžitě selže s chybou no_target_languages, místo aby se importoval dokument bez cílových jazyků. Volání vrátí processing_job_id; dotazujte se pomocí GET /document-jobs/{id}, dokud import neskončí a nezískáte ID dokumentů.

Překlady, které soubor již obsahuje (targets: {de: "…"}), se naimportují jako aktivní překlady jednotlivých řetězců. Je to zdarma, nevyžaduje to spuštění překladu a okamžitě se tím plní vaše překladová paměť. Funguje to stejně jako nahrání stávajících překladů přes aplikaci.

# 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}

Na endpoint POST /documents/{id}/import-strings odešlete znovu celý aktuální katalog, nikoli jeho zkrácenou verzi. Server jej porovná podle ID jednotek a v odpovědi uvede, co zjistil (added, changed, unchanged, removed), spolu s delta_block_ids: konkrétními bloky pro každou jazykovou verzi, které vyžadují zpracování. Tento objekt předejte beze změn jako parametr block_ids pro hromadné spuštění a přeloží se pouze tyto bloky. Parametr run můžete také předat přímo při opětovném importu, čímž zpracování rozdílů spustíte v rámci stejného volání.

U nezměněných jednotek zůstávají zachovány jejich překlady i stav případných revizí; jde o ekvivalent funkce Spustit pouze pro změněný obsah v rámci API. Oprava jednoho řetězce v katalogu se stovkami položek vás tak stojí skutečně jen jeden řetězec.

# 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 na hlavním dokumentu vrátí jeden soubor .tstrings.json s překlady ve všech jazycích klíčovanými podle ID jednotek: stačí jedno volání a výsledek je připraven k uložení do repozitáře nebo k integraci do vašeho buildu. Stejný endpoint poskytuje i verze pro jednotlivé jazyky (markdown, html, csv, xliff, tmx), pokud vaše pipeline vyžaduje konkrétní přenosový formát; kompletní tabulku najdete v sekci Automatizace služby Transept pomocí API.

U katalogů importovaných ve formátech CSV, PO nebo XLIFF vyplní export v původním formátu přímo buňky a záznamy vašeho souboru (soubor zůstane bajt po bajtu stejný jako při nahrávání, jen přibudou překlady). Výsledek tak můžete nahrát přímo zpět do systému, ze kterého pochází.

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