Localización integral mediante API: cadenas de texto, correos y documentos

Un script puede hacer todo lo que permite el editor: importar, traducir a múltiples idiomas con sus glosarios y memorias de traducción, revisar y exportar. Esta guía le guiará desde la obtención de la clave hasta la traducción final, recorriendo después cada etapa del ciclo. La referencia interactiva y el JSON de OpenAPI constituyen la especificación técnica completa; transept.ai/developers es la versión resumida de esta guía. Una peculiaridad terminológica antes de la primera llamada: la unidad de facturación se denomina palabras en la interfaz de usuario, pero los campos de respuesta de la API conservan el nombre histórico credits (estimatedCredits, spendable). Se trata de la misma cantidad.

Obtener una clave

Configuración → Desarrollador en la aplicación; copie la clave secreta una sola vez. Las solicitudes la envían como Authorization: Bearer tsk_live_…, solo en el encabezado, nunca en la URL.

Las claves de API tienen permisos restringidos: acceso total o de lectura y escritura por área (documentos, ejecuciones, glosarios, guías de estilo, memoria de traducción, webhooks o proyectos). Si una llamada excede el alcance de la clave, recibirá un error 403 que indicará el permiso faltante. Una clave nunca puede generar otra; la gestión de claves se realiza exclusivamente desde la aplicación.

El ciclo en cinco llamadas

Verifique que la clave funciona, cree un documento, calcule el coste de la ejecución, iníciela y recupere el 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"

Tres recomendaciones fundamentales: solicite primero un presupuesto (es gratuito; el rango va del mínimo al máximo, y este último se ajusta al gasto real), **envíe una ****Idempotency-Key** en las peticiones POST de creación de tareas (así, cualquier reintento devuelve el resultado original en lugar de generar un doble cargo) y registre un webhook (POST /webhooks {url, events: ["group_run.completed"]}) en lugar de realizar consultas constantes. Las notificaciones están firmadas mediante HMAC e incluyen reintentos y un registro de envíos.

Tres tipos de entrada

Texto libre y correos electrónicos

POST /documents con content_type: "html" mantiene el formato, los enlaces y los marcadores de posición de las plantillas durante la traducción; format=html devuelve el correo traducido con su estructura original. También puede saltarse la solicitud: configure un activador de flujo de trabajo como "el cuerpo de la solicitud es el contenido" y vincule su ESP, Zapier/n8n o CI a la URL del activador:

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

El activador determina si cada envío crea un documento nuevo o actualiza un único documento fijo (al actualizar, el contenido se realinea para que solo se vuelvan a traducir los bloques modificados). Los envíos repetidos se desduplican mediante el external_id o el hash del contenido durante 24 horas. Consulte los activadores por webhook.

Archivos

POST /documents/upload (multipart) con el archivo más source_language, target_language y, opcionalmente, target_languages[] y project_id. Los archivos DOCX permiten un ciclo de ida y vuelta: al exportar, las traducciones se reinsertan en el archivo original, lo que permite conservar el estilo y el diseño intactos. Los formatos CSV, PO y XLIFF se importan como unidades con clave y se vuelven a exportar en su formato original. Detalles de formato y mapeo de columnas: archivos de cadenas.

Catálogos de cadenas

Cada cadena es una unidad con un id estable, un source y campos opcionales para context, max_length y 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}

El campo context llega al modelo como guía para la traducción, max_length se aplica mediante un proceso de acortamiento y reintento, los marcadores de posición se protegen y los plurales se expanden según cada idioma. Las traducciones que ya incluya el archivo se incorporan como activas sin coste y alimentan la memoria de traducción. Si faltan los idiomas de destino, la llamada fallará con el error no_target_languages en lugar de importar un documento que no se traduciría a nada. El flujo completo se detalla en Localizar un catálogo de cadenas mediante la API.

Una plantilla de correo, tres idiomas

Veamos el caso de un correo electrónico en detalle. El código Liquid se mantiene intacto durante la traducción:

# 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 | … }} se oculta antes de que el modelo procese el texto y se restaura íntegramente, con una excepción: el valor predeterminado friend es un texto visible para el lector, por lo que SÍ se traduce, a diferencia de la etiqueta que lo rodea. Ejecute el grupo como se indica en la guía de inicio rápido y, a continuación, recupere el contenido 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: un activador por webhook de carga útil recibe la plantilla directamente del ESP, el flujo de trabajo se inicia en cuanto llega y un webhook group_run.completed devuelve el HTML traducido. Detalles específicos de cada plataforma (etiquetas de Braze, condicionales de Mailchimp): plantillas de correo de ESP y la guía de localización de correos electrónicos.

Glosarios, guías de estilo y memoria

Cree un glosario e incorpore términos en la misma llamada:

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

Amplíe uno existente (use GET /glossaries para ver los disponibles para su clave):

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

O genérelos a partir de un documento de confianza: POST /glossaries/{id}/auto-build y POST /styleguides/generate, ambos con su versión gratuita …/estimate equivalente. Ambos facturan por palabra y requieren auto_apply: true a través de la API; al ser un proceso desatendido sin etapa de revisión, el resultado se confirma al finalizar. Consulte el estado en GET /generation-jobs/{id}. La alternativa para revisarlos en la aplicación: crear a partir de un documento. Vincúlelos una sola vez y se aplicarán en cada ejecución posterior —desde la API, el MCP o el editor— sin coste 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>"]}'

Las guías de estilo se vinculan mediante el ID de la versión activa (obtenido de GET /styleguides/{id}); [] las desvincula; ambos funcionan también en POST /documents al momento de la creación. En la interfaz: glosarios, guías de estilo. La memoria de traducción no requiere vinculación: cada traducción completada se indexa y se reutiliza automáticamente. Puede consultarla (POST /translation-memory/query, sin coste), alimentarla desde un TMX/XLIFF (POST /translation-memory/import, sin coste) o exportarla íntegramente (GET /translation-memory/export-tmx). Consulte memoria de traducción e importar traducciones existentes.

Equipos

Las claves de equipo facturan al fondo común del equipo y heredan sus proyectos, glosarios, guías de estilo y memoria de traducción. Para crear documentos en un equipo, proporcione el project_id de un proyecto del equipo (puede obtenerlos con GET /projects; los proyectos de equipo incluyen un team_id). En todo lo demás, el funcionamiento es idéntico al uso personal. Los equipos y proyectos se configuran desde la aplicación: proyectos, equipos e invitaciones.

Ejecuciones y controles de revisión

POST /runs procesa una única versión de idioma, mientras que POST /group-runs se distribuye entre todos los idiomas de destino y crea las versiones que falten según sea necesario. Ambos permiten obtener una estimación gratuita, admiten la cabecera Idempotency-Key y pueden cancelarse. Si un paso del flujo de trabajo está configurado para esperar revisión, la ejecución se detendrá: GET /runs/{id} devolverá gate_pending: true junto con un resumen de los hallazgos de la revisión. El proceso manual se gestiona desde el panel de revisión y la revisión guiada; por la parte del 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"

Un control de revisión nunca se reanuda de forma automática: es necesario llamar a la función de aprobación, ya sea mediante su script, un asistente a través de MCP o una persona desde la aplicación. No existe ningún parámetro al iniciar la ejecución que apruebe los controles de antemano; si no desea que el proceso se detenga en ningún momento, utilice un flujo de trabajo que no incluya pasos de revisión.

Formatos de salida

GET /documents/{id}/content?format=<f> aplicado al id de una versión de idioma:

Al usar format=strings en el documento maestro, se devuelven todos los idiomas en una sola llamada, listos para confirmar.

Actualizar solo los cambios

Para los catálogos de cadenas, vuelva a enviar el archivo completo; el servidor se encarga de gestionar las diferencias:

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

Las cadenas que no cambian conservan su traducción y su estado de revisión; corregir una sola cadena solo cuesta una cadena. (Pase run: {template_id} al reimportar para procesar los cambios en la misma llamada). Esta es la versión para API de Procesar solo lo que ha cambiado. En documentos de prosa cuyo origen haya variado, POST /documents/{id}/resync-source vuelve a alinear los bloques: los que no han cambiado mantienen sus traducciones, los modificados quedan obsoletos y una ejecución de "solo actualizados" afectará únicamente a estos últimos. La resincronización vuelve a procesar el archivo original almacenado, por lo que las ediciones del origen deben realizarse mediante la importación y no modificando los bloques directamente.

Asistentes de IA (MCP)

Sigue el mismo flujo que las herramientas de agentes, disponible en https://app.transept.ai/api/public/v1/mcp: me_get → document_create → group_run_estimate / group_run_start → group_run_get → document_content_get. La conexión se realiza vía OAuth (consentimiento en el navegador, sin necesidad de copiar claves; para entornos headless, se puede usar una clave Bearer). Las herramientas respetan los permisos concedidos y cualquier acción que consuma palabras responde primero con un presupuesto; el asistente debe confirmar la operación explícitamente. Configuración por cliente: Conectar su asistente de IA.

Preguntas frecuentes

¿Las estimaciones, las reimportaciones o las traducciones incorporadas consumen palabras?

No. Las estimaciones son gratuitas y no conllevan efectos secundarios. Reimportar un catálogo no tiene coste (el servidor procesa las diferencias) y las traducciones que ya incluyan sus archivos se incorporan como trabajo finalizado sin cargo alguno. Solo se consumen palabras cuando Transept traduce contenido para usted. Al final, las estimaciones máximas se ajustan al gasto real, liberando la reserva no utilizada.

¿Puede la automatización saltarse mis controles de revisión?

No. Si un paso del flujo de trabajo está configurado para esperar una revisión, la ejecución se detiene hasta que alguien o algo la apruebe: ya sea un script que llame al endpoint de aprobación o una persona desde la aplicación. Si un proceso debe ejecutarse de principio a fin sin intervención, configure su flujo de trabajo sin pasos de revisión; no existe ningún parámetro que permita omitir un control que usted mismo haya incluido.

¿Está disponible la API en el plan gratuito?

Sí. Las claves de API están disponibles en todos los planes, incluido el gratuito; no hay requisitos de acceso adicionales. El límite de uso lo marca su saldo de palabras, exactamente igual que en el editor, y el cupo mensual de palabras del plan gratuito se aplica a la API de la misma forma que en cualquier otra parte.

¿Cómo puedo localizar plantillas de correo electrónico sin exportarlas a mano?

Vincule su plataforma de correo electrónico a un activador de webhook: el cuerpo de la plantilla enviado por POST se convierte en el documento, el flujo de trabajo lo traduce y la exportación devuelve la misma estructura HTML con las traducciones ya aplicadas. Los marcadores de posición y la sintaxis de la plantilla se mantienen protegidos durante todo el proceso. Los detalles técnicos de cada plataforma se encuentran en la guía de localización de correos electrónicos.

¿Dónde está la referencia exhaustiva de los endpoints?

En la referencia interactiva de Swagger, generada a partir de la misma especificación OpenAPI que puede importar en n8n, Zapier o un generador de código (JSON sin procesar). Esta guía sirve como introducción narrativa; la especificación técnica es el contrato.