Localização via API: strings, e-mails e documentos de ponta a ponta

Tudo o que o editor faz, um script também pode fazer: importar, traduzir em diversos idiomas com seu glossário e memória de tradução, revisar e exportar. Este guia conduz você da chave ao resultado traduzido e, em seguida, por cada etapa do ciclo. A referência interativa e o JSON da OpenAPI são a especificação completa; transept.ai/developers é a versão resumida deste guia. Uma particularidade de nomenclatura antes da primeira chamada: a unidade de faturamento aparece como palavras em todas as interfaces de leitura, mas os campos de resposta da API mantêm o nome histórico credits (estimatedCredits, spendable). O valor é o mesmo.

Obter uma chave

Configurações → Desenvolvedor no app; copie o segredo uma única vez. Envie-o nas requisições como Authorization: Bearer tsk_live_…, apenas no cabeçalho, nunca na URL.

As chaves possuem escopos: acesso total ou leitura/gravação por área (documentos, execuções, glossários, guias de estilo, memórias de tradução, webhooks e projetos). Chamadas fora dos escopos da chave recebem um 403 que especifica o que falta. Uma chave nunca pode gerar outra chave; o gerenciamento de chaves é feito exclusivamente no aplicativo.

O ciclo em cinco chamadas

Valide a chave, crie um documento, estime o custo da execução, inicie o processo e obtenha o resultado.

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"

Três hábitos para adotar desde o primeiro dia: estimar primeiro (gratuito; o intervalo vai do mínimo ao máximo, e o teto se ajusta ao gasto real), **enviar uma ****Idempotency-Key** em POSTs de criação de tarefas (uma nova tentativa repete o primeiro resultado em vez de cobrar em dobro) e registrar um webhook (POST /webhooks {url, events: ["group_run.completed"]}) em vez de fazer polling. As entregas são assinadas via HMAC, com tentativas de reenvio e log de entrega.

Três formatos de entrada

Prosa e e-mail

O POST /documents com content_type: "html" preserva a formatação, os links e os marcadores de posição do modelo durante a tradução; format=html retorna o e-mail traduzido com a mesma estrutura. Ou pule a requisição: configure um gatilho de workflow para "o corpo da requisição é o conteúdo" e aponte seu ESP, Zapier/n8n ou CI para a URL do gatilho:

# 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.'

O gatilho determina se cada envio cria um novo documento ou atualiza um documento fixo (a atualização realinha o conteúdo para que apenas os blocos alterados sejam traduzidos novamente). Envios repetidos são deduplicados pelo external_id ou pelo hash do conteúdo por 24 horas. Confira os gatilhos de webhook.

Arquivos

POST /documents/upload (multipart) com o arquivo, além de source_language, target_language e os parâmetros opcionais target_languages[] e project_id. O DOCX suporta o fluxo de ida e volta: a exportação reinsere as traduções no arquivo original, mantendo o estilo e o layout intactos. Já os arquivos CSV, PO e XLIFF são importados como unidades indexadas por chaves e exportados de volta em seus formatos originais. Detalhes de formato e mapeamento de colunas: arquivos de strings.

Catálogos de strings

Cada string é uma unidade com um id estável, um source e os campos opcionais context, max_length e 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}

O contexto chega ao modelo como orientação de tradução, o max_length é aplicado por meio de encurtamento e nova tentativa, os marcadores são protegidos e os plurais são expandidos para cada idioma. Traduções já presentes no arquivo são inseridas como ativas sem custo e alimentam a memória de tradução. A ausência de idiomas de destino faz a chamada falhar com no_target_languages, em vez de importar um documento que não geraria resultados. O fluxo completo está em Localizar um catálogo de strings via API.

Um modelo de e-mail, três idiomas

O caso do e-mail, na prática. A sintaxe Liquid permanece intacta durante a tradução:

# 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 | … }} é mascarado antes de o modelo processar o texto e restaurado literalmente, com uma única exceção: o valor padrão friend é um conteúdo voltado ao leitor e, por isso, ELE É traduzido, enquanto a tag ao seu redor permanece intacta. Execute o grupo seguindo o guia de início rápido e, em seguida, recupere o conteúdo de cada idioma:

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

Variante totalmente automatizada: um gatilho de webhook de payload captura o modelo diretamente do ESP, o workflow é executado no recebimento e um webhook group_run.completed devolve o HTML traduzido. Especificidades de plataforma (tags do Braze, condicionais do Mailchimp): modelos de e-mail de ESP e o guia de localização de e-mail.

Glossários, guias de estilo e memória

Crie um glossário e adicione os termos na mesma chamada:

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}]}'

Amplie um glossário existente (GET /glossaries lista os itens visíveis para sua chave):

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

Ou gere a partir de um documento de confiança: POST /glossaries/{id}/auto-build e POST /styleguides/generate, cada um com seu respectivo …/estimate gratuito. Ambos são tarifados por palavra e exigem auto_apply: true via API; como o modo headless não possui etapa de revisão, o resultado é efetivado assim que a operação termina. Acompanhe o status com GET /generation-jobs/{id}. A alternativa com revisão no app: criar a partir de um documento. Vincule-os uma única vez e todas as execuções posteriores os utilizarão — seja via API, MCP ou no editor — sem custo adicional:

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

Vincule guias de estilo pelo ID da versão ativa (obtido via GET /styleguides/{id}); o uso de [] os desvincula. Ambos os parâmetros também funcionam no POST /documents no momento da criação. Na interface: glossários, guias de estilo. A memória de tradução não requer vinculação: cada tradução concluída é indexada e reutilizada automaticamente. Você pode consultá-la (POST /translation-memory/query, gratuito), alimentá-la com um TMX/XLIFF (POST /translation-memory/import, gratuito) ou exportar tudo (GET /translation-memory/export-tmx). Veja memória de tradução e importar traduções existentes.

Equipes

Uma chave de equipe debita do saldo da equipe e herda seus projetos, glossários, guias de estilo e memória de tradução. Para criar documentos na equipe, informe o project_id de um projeto dela (GET /projects; projetos de equipe possuem um team_id). Nos demais aspectos, o funcionamento é idêntico ao uso pessoal. Equipes e projetos são configurados no app: projetos, equipes e convites.

Execuções e etapas de revisão

POST /runs processa uma única versão de idioma; o POST /group-runs abrange todos os idiomas de destino, criando as versões que faltarem conforme necessário. Ambos oferecem estimativas gratuitas, aceitam Idempotency-Key e permitem cancelamento. Uma etapa de workflow configurada para aguardar revisão interrompe a execução: o GET /runs/{id} reporta gate_pending: true com um resumo do que a revisão encontrou. O lado humano da pausa é o painel de revisão e a revisão guiada; o lado do script:

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

Uma etapa de revisão nunca avança sozinha: algo precisa acionar a aprovação, seja o seu script, um assistente via MCP ou uma pessoa no app. Não existe uma flag de início de execução que pré-aprove as etapas; se não quiser nenhuma pausa, use um workflow sem etapas de revisão.

Formatos de saída

GET /documents/{id}/content?format=<f> em um ID de versão de idioma:

O parâmetro format=strings no documento mestre retorna todos os idiomas em uma única chamada, prontos para o commit.

Atualize apenas as alterações

Para catálogos de strings, reenvie o arquivo atual completo; o servidor processa o diff:

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

Strings inalteradas mantêm suas traduções e seu estado de revisão; corrigir uma string custa uma string. (Passe run: {template_id} inline na reimportação para processar o delta na mesma chamada.) Esta é a versão para API de Executar apenas o que mudou. Para documentos de texto corrido cuja origem foi alterada, o POST /documents/{id}/resync-source realinha os blocos: blocos inalterados mantêm suas traduções, os alterados tornam-se obsoletos e uma execução de apenas atualizados afeta somente estes. A ressincronização reprocessa o arquivo de origem armazenado; portanto, edite as fontes pelo fluxo de importação, não via patch nos blocos.

Assistentes de IA (MCP)

O fluxo é o mesmo das ferramentas de agentes, em https://app.transept.ai/api/public/v1/mcp: me_get → document_create → group_run_estimate / group_run_start → group_run_get → document_content_get. A conexão é feita via OAuth (consentimento pelo navegador, sem chaves para colar; tokens Bearer funcionam para acesso headless). As ferramentas respeitam as permissões concedidas, e qualquer ação que consuma palavras retorna primeiro uma estimativa; o assistente deve confirmar explicitamente. Configuração por cliente: Conecte seu assistente de IA.

Perguntas frequentes

Estimativas, reimportações ou traduções preexistentes consomem palavras?

Não. As estimativas são gratuitas e não geram efeitos colaterais; a reimportação de catálogos também não tem custo (o diff é calculado no servidor), e as traduções que seus arquivos já contêm são importadas como trabalho concluído sem cobrança. Você só consome palavras quando o Transept traduz algo para você. As estimativas de limite máximo são ajustadas ao gasto real, liberando a reserva não utilizada.

A automação pode ignorar minhas etapas de revisão?

Não. Uma etapa do fluxo de trabalho configurada para aguardar revisão pausa a execução até que algo a aprove: seja o seu script chamando o endpoint gate-approve ou uma pessoa no aplicativo. Se um pipeline precisar rodar de ponta a ponta sem supervisão, configure o fluxo de trabalho sem etapas de revisão; não existe um parâmetro que ignore uma barreira que você mesmo colocou lá.

A API está disponível no plano Gratuito?

Sim. As chaves de API estão disponíveis em todos os planos, inclusive no Gratuito; não há restrições adicionais. O que limita o uso é o seu saldo de palavras, exatamente como no editor, e o volume mensal de palavras do plano Gratuito funciona via API da mesma forma que em qualquer outro lugar.

Como localizar templates de e-mail sem precisar exportá-los manualmente?

Basta apontar sua plataforma de e-mail para um gatilho de webhook: o corpo do template enviado via POST se torna o documento, o fluxo de trabalho realiza a tradução e a exportação devolve a mesma estrutura HTML com os textos traduzidos. Placeholders e sintaxes de template permanecem protegidos durante todo o ciclo. Os detalhes técnicos para cada plataforma estão no guia de localização de e-mails.

Onde encontro a referência completa dos endpoints?

A referência interativa do Swagger é gerada a partir da mesma especificação OpenAPI que você pode importar no n8n, no Zapier ou em um gerador de código (JSON bruto). Este guia funciona como um ponto de partida narrativo; a especificação é o contrato.