Localize um catálogo de strings via API

O formato indexado do Transept é o .tstrings.json: uma lista de unidades, cada uma com um id estável, um source e, opcionalmente, um context (o que a string é e onde aparece), um max_length e placeholders. O id é o contrato: é ele que garante a identidade das traduções em novas importações, preserva o estado da revisão e permite que a exportação indexe todos os idiomas. Ambos os recursos extras têm utilidade real: o contexto serve de guia para o modelo de tradução, e o limite de caracteres é aplicado por meio de uma rotina automática de encurtar e tentar novamente.

Arquivos CSV, gettext PO e XLIFF são importados como as mesmas unidades indexadas pelo app ou pelo endpoint de upload; veja arquivos de strings para saber como cada formato é mapeado. Este artigo foca em gerenciar o ciclo via código, no qual o .tstrings.json é o formato nativo.

POST /documents/import-strings com o catálogo em JSON. Os idiomas de destino são resolvidos em uma ordem fixa: um target_language / target_languages explícito na requisição tem prioridade; caso contrário, usam-se os target_locales do cabeçalho do catálogo; se nenhum for encontrado, a chamada falha imediatamente com no_target_languages em vez de importar um documento sem destinos. A chamada retorna um processing_job_id; faça o polling de GET /document-jobs/{id} até que a importação termine e você tenha os IDs dos documentos.

As traduções que o arquivo já contém (targets: {de: "…"}) são inseridas como a tradução ativa de cada string, sem custo e sem necessidade de execução, e alimentam sua memória de tradução imediatamente — o mesmo comportamento de trazer traduções existentes pelo app.

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

Reenvie o catálogo atual completo para POST /documents/{id}/import-strings, em vez de um arquivo reduzido. O servidor faz a comparação pelo ID da unidade e responde com o que encontrou (added, changed, unchanged, removed), além dos delta_block_ids: os blocos exatos que precisam de processamento, por versão de idioma. Passe esse objeto exatamente como está no campo block_ids de uma execução em grupo e apenas esses blocos serão traduzidos; você também pode passar run inline no reenvio para processar o delta na mesma chamada.

As unidades inalteradas mantêm suas traduções e qualquer revisão já realizada nelas; esta é a versão via API do recurso Traduzir apenas o que mudou. Corrigir uma única string em um catálogo com centenas custa apenas uma string.

# 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>", "…"] }}'

O GET /documents/{id}/content?format=strings no documento mestre retorna um arquivo .tstrings.json com as traduções de todos os idiomas indexadas pelo ID da unidade: uma única chamada, pronta para o commit ou para ser reintegrada ao seu build. O mesmo endpoint fornece versões por idioma (markdown, html, csv, xliff, tmx) quando um pipeline precisa de um formato de transmissão específico; a tabela completa está em Automatize o Transept via API.

Para catálogos importados como CSV, PO ou XLIFF, a exportação no formato original preenche as células e entradas do seu próprio arquivo (exatamente o que você enviou, byte a byte, com as traduções adicionadas), permitindo que o arquivo seja carregado diretamente de volta no sistema de origem.

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