Traducir documentos

Un documento se traduce en segundo plano. Lo subes, la API responde al momento con un trabajo, y vuelves a por el fichero traducido, en el mismo formato y con la misma maquetación.

Formatos

• Office: DOCX, XLSX, PPTX y sus variantes con macros y plantillas.
• OpenDocument: ODT, ODS, ODP, ODG y sus plantillas.
• Web y texto: HTML, XHTML, TXT, Markdown.
• Software: JSON, YAML, PO, properties de Java.

Un fichero puede pesar hasta 50 MB.

1. Sube el documento

POST /v1/jobs recibe un formulario (multipart/form-data) con el fichero y los dos idiomas. Responde 202 con el trabajo, en cola.

curl https://api.translaqe.com/v1/jobs \
  -H "Authorization: Bearer $TRANSLAQE_API_KEY" \
  -H "Idempotency-Key: contract-2026-10-12" \
  -F "[email protected]" \
  -F "source_lang=es" \
  -F "target_lang=en" \
  -F "glossary_ids=gl_3f9a1c2b7d5e4f60a1b2c3d4e5f60718" \
  -F "webhook_url=https://example.com/hooks/translaqe"

Campo	Para qué es
file	El documento.
source_lang, target_lang	El idioma en el que está y el idioma al que lo quieres.
memory_ids, glossary_ids	Memorias y glosarios con los que traducir, separados por comas.
project_id	Un proyecto: se usan sus memorias y sus glosarios, y el trabajo sale en su lista.
webhook_url	Una dirección HTTPS a la que avisar cuando el trabajo acabe.
notify_email	Un correo al que avisar cuando el trabajo acabe.
allow_partial	Entregar el fichero aunque alguna frase no se pueda traducir.

Manda la cabecera Idempotency-Key con un valor tuyo. Si se corta la conexión y vuelves a mandar la subida con el mismo valor, recibes el mismo trabajo (200) en vez de traducir, y gastar, el fichero dos veces.

2. Espera a que acabe

Pide el trabajo cada pocos segundos hasta que su status sea uno de los finales:

Estado	Qué significa
queued	Esperando su turno.
running	En marcha: stage dice en qué etapa (extracting, translating, scoring, rebuilding) y progress, cuánto lleva.
retrying	Ha fallado y se va a intentar otra vez.
succeeded	Hecho: result trae las cifras y el fichero está listo.
failed	No se ha podido: error_code dice por qué.
cancelled	Lo cancelaste.

JOB=job_8c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f

# Ask until it is over: succeeded, failed or cancelled.
while true; do
  STATUS=$(curl -s "https://api.translaqe.com/v1/jobs/$JOB" \
    -H "Authorization: Bearer $TRANSLAQE_API_KEY" | jq -r .status)
  case "$STATUS" in succeeded|failed|cancelled) break ;; esac
  sleep 5
done

# -OJ saves the file under the name the API gives it.
[ "$STATUS" = succeeded ] && curl -sOJ "https://api.translaqe.com/v1/jobs/$JOB/file" \
  -H "Authorization: Bearer $TRANSLAQE_API_KEY"

O que te avisemos nosotros

Con webhook_url, cuando el trabajo acaba, bien o mal, se manda un POST a tu dirección:

POST /hooks/translaqe HTTP/1.1
Content-Type: application/json
User-Agent: TranslaQE-Webhook/1
X-TranslaQE-Event: job.succeeded
X-TranslaQE-Delivery: 5b0e…

{
  "job_id": "job_8c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f",
  "status": "succeeded",
  "error_code": null,
  "sent_at": "2026-10-12T09:31:47+00:00"
}

Los avisos son job.succeeded y job.failed, y para las memorias y los glosarios resource.ready y resource.failed, que llevan además resource_id y kind. Un trabajo cancelado no avisa.

El aviso no lleva contenido y no va firmado. Tómalo como una pista: cuando llegue, pide el trabajo con tu clave y actúa según lo que diga la API.

3. Descarga

GET /v1/jobs/{job_id}/file devuelve el fichero traducido. Su nombre va en la cabecera Content-Disposition. Antes de que el trabajo acabe bien, la respuesta es 409 con el tipo job-not-ready.

result dice cómo ha ido: la nota media, cuántas frases tienen menos de 60 (low_score_segments) y en cuántas hubo que arreglar una marca de formato (mark_warnings).

Cuando una frase no se puede traducir

Si ningún modelo sabe traducir alguna frase, el trabajo acaba failed con error_code: "partial" y sin fichero: no se entrega un documento con huecos sin que lo sepas. Hay dos salidas:

• Subirlo con allow_partial: true. El fichero se entrega con esas frases en el idioma de origen, y result.failed_segments dice cuántas son.
• Escribir tú las traducciones que faltan (abajo) y volver a montar el fichero.

Revisar y corregir

Todas las frases del documento están en GET /v1/jobs/{job_id}/segments, con su origen, su traducción, su nota y su estado. Filtra por band para ir directo a las que hay que mirar, corrígelas con PATCH y pide que se monte el fichero otra vez.

JOB=job_8c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f
AUTH="Authorization: Bearer $TRANSLAQE_API_KEY"

# 1. The sentences that need another translation.
curl -s "https://api.translaqe.com/v1/jobs/$JOB/segments?band=rehacer" -H "$AUTH"

# 2. Correct one of them.
curl -s -X PATCH "https://api.translaqe.com/v1/jobs/$JOB/segments/12" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"target": "The rate in force at the time of the order will apply.", "state": "approved_translation"}'

# 3. Build the file again with the corrections.
curl -s -X POST "https://api.translaqe.com/v1/jobs/$JOB/rebuild" -H "$AUTH"

# 4. Keep what was approved in a memory, for next time.
curl -s -X POST "https://api.translaqe.com/v1/jobs/$JOB/review" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"memory_id": "tm_5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d"}'

• Una frase corregida pasa a ser de una persona (origin: "interactive") y pierde su nota.
• La traducción tiene que llevar las marcas de formato del origen (<g1>…</g1>, <x1/>): son las que vuelven a poner en su sitio las negritas, los enlaces y los saltos de línea.
• POST /v1/jobs/{job_id}/rebuild no gasta caracteres: no se traduce nada otra vez.
• POST /v1/jobs/{job_id}/review manda a una memoria lo que una persona escribió o aprobó. El siguiente documento que repita esas frases las saca de la memoria.

Limpiar

DELETE /v1/jobs/{job_id} borra el trabajo con sus frases y sus ficheros, el original y el traducido. Uno que está en cola o en marcha hay que cancelarlo antes, con POST /v1/jobs/{job_id}/cancel.