Cada etapa habilitada del pipeline deja un registro en el trabajo, para que puedas ver qué se ejecutó en lugar de simplemente asumirlo.
Activaste algunas etapas del pipeline, quizá pre-edit para limpiar el texto fuente y back-translation para detectar desvíos, y un trabajo regresó completed_with_warnings. ¿Qué etapa falló? ¿La persona encargada de la revisión humana llegó a tomarlo o se venció el tiempo? ¿Cuánto costaron las etapas extra? Un pipeline que ejecuta varios pasos de IA y humanos por idioma es justo el tipo de proceso que puede volverse una caja negra: sale un resultado y terminas confiando en que las etapas intermedias hicieron su trabajo.
Aquí no te piden que confíes a ciegas. Cada etapa habilitada escribe un registro en el arreglo steps[] del trabajo: qué etapa fue, qué estado tuvo, cuánto costó y cuándo empezó y terminó. Ves lo que hizo cada etapa; no solo confías en que se ejecutó. Ese es, en esencia, el propósito de esta página.
¿Recién empiezas con el pipeline? Comienza con la Descripción general del pipeline.
En esta página
- Dónde están los registros
- El arreglo steps
- Cómo mapear un stepId a una etapa
- Estado de una etapa: completed, failed, skipped
- Cómo una falla en una etapa se convierte en una advertencia del trabajo
Dónde están los registros#
El arreglo steps[] es un campo del trabajo de localización. No se obtiene por separado: llega cada vez que lees el trabajo:
GET /jobs/localization/:jobIdAutentícate con tu API key en el encabezado X-API-Key. El endpoint completo, los valores de estado del trabajo y la carga útil outputData se explican en la página del trabajo individual; esta página se enfoca en un campo de esa respuesta —el rastro por etapa— y en lo que te permite ver.
La regla, entonces, es simple: cada trabajo que lees ya trae su propio registro de auditoría. Un trabajo sin pipeline habilitado muestra un solo registro, porque core localization siempre se ejecuta. Activa dos etapas opcionales y verás tres registros. El arreglo crece con el pipeline, una entrada por etapa, en el orden en que se ejecutaron.
El arreglo steps#
Cada entrada en steps[] es el registro de una etapa. Estos son los campos que debes leer para auditar una ejecución: qué etapa fue, cuál fue el resultado, cuánto costó y cuándo ocurrió:
"steps": [
{
"stepId": "preEdit",
"type": "action",
"status": "completed",
"errorMessage": null,
"costUsd": 0.0012,
"externalRefType": null,
"externalRefId": null,
"externalRefUrl": null,
"createdAt": "2026-03-16T10:30:01.000Z",
"startedAt": "2026-03-16T10:30:01.000Z",
"completedAt": "2026-03-16T10:30:02.000Z"
},
{
"stepId": "localize",
"type": "action",
"status": "completed",
"errorMessage": null,
"costUsd": 0.0184,
"externalRefType": null,
"externalRefId": null,
"externalRefUrl": null,
"createdAt": "2026-03-16T10:30:02.000Z",
"startedAt": "2026-03-16T10:30:02.000Z",
"completedAt": "2026-03-16T10:30:05.000Z"
}
]| Campo | Descripción |
|---|---|
stepId | Indica a qué etapa del pipeline corresponde este registro. Consulta la tabla de mapeo más abajo. |
type | El tipo de paso. action para una etapa automatizada. |
status | completed, failed o skipped para esta etapa, independientemente del estado del trabajo. |
errorMessage | Por qué falló esta etapa. null, a menos que status sea failed. |
costUsd | Cuánto costó esta etapa, en USD: un número JSON o null. |
externalRefType, externalRefId, externalRefUrl | Un puntero a un registro externo para etapas que derivan trabajo a un tercero: la etapa de revisión humana. null para etapas totalmente automatizadas. |
createdAt, startedAt, completedAt | Cuándo se creó la etapa, cuándo fue tomada y cuándo terminó. |
Cada registro también incluye un campo outputData: el contenido que produjo esa etapa, con la misma forma que el outputData del trabajo. Esa carga útil es la traducción, no el rastro de auditoría, así que está documentada en la página del trabajo individual junto con el outputData a nivel de trabajo; los campos de arriba son los que debes leer para ver qué hizo el pipeline.
Hay dos cosas que estos registros te dan y que un solo bloque de outputData no puede darte. Primero, el costo se desglosa por etapa, no solo como total por trabajo; así que cuando habilitas back-translation y cambia la factura, puedes ver exactamente qué etapa la movió. Segundo, los tiempos se registran por etapa: un registro humanEdit cuyo startedAt y completedAt están separados por horas te dice que la espera fue humana, no del motor.
Lee steps por stepId, no por posición
Los registros aparecen en orden de ejecución, pero no indexes el arreglo por posición: las etapas que se ejecutan dependen de cuáles habilitaste, así que la posición no es estable entre trabajos. Encuentra una etapa por su stepId (steps.find(s => s.stepId === "humanEdit")). El conjunto de valores stepId es fijo; el conjunto presente en cualquier trabajo es el que activaste.
Cómo mapear un stepId a una etapa#
Cada stepId identifica una etapa del pipeline. Esta es la tabla de referencia que va del valor en el registro a la etapa que representa y a la página que documenta lo que hace esa etapa:
stepId | Etapa |
|---|---|
preEdit | Edición con IA previa a la localización |
localize | Core localization |
humanEdit | Revisión humana posterior a la localización |
postEdit | evaluación de IA posterior a la localización |
rephrase | Reformular para que suene natural |
backTranslation | Verificación de back-translation |
localize es el único stepId que aparece en todos los trabajos, haya pipeline o no: es el paso central de traducción y siempre se ejecuta. Los otros cinco solo aparecen cuando habilitaste esa etapa en el motor o en la solicitud.
Estado de una etapa: completed, failed, skipped#
Cada paso tiene su propio status, establecido de forma independiente del trabajo y de cualquier otro paso. Son tres valores:
status de la etapa | Significado |
|---|---|
completed | La etapa se ejecutó y produjo su resultado. |
failed | La etapa se ejecutó y falló. errorMessage indica por qué. |
skipped | La etapa no llegó a completarse esta vez, aunque estaba habilitada. |
completed y failed se entienden como esperarías. skipped es el que merece una pausa, porque no es lo mismo que "disabled". Una etapa que nunca activaste no genera ningún registro. Un registro skipped significa que la etapa sí estaba habilitada, pero se pasó por alto por una razón definida por el pipeline. El caso más claro es la revisión humana: si la ventana de revisión se cierra sin respuesta humana, esa etapa se marca como skipped y la traducción de IA sigue adelante como definitiva. El registro sigue ahí, así que la omisión queda visible en lugar de pasar desapercibida.
El estado de una etapa no es el estado del trabajo
Que un paso sea failed no siempre significa que el trabajo sea failed. La mayoría de las etapas opcionales no son críticas: cuando una falla, su registro aparece como failed, el motor conserva el último resultado válido y el trabajo aun así termina con un outputData completo. El estado de trabajo resultante, completed_with_warnings, se explica en la página del trabajo individual. El estado de la etapa te dice qué pasó en una etapa; el estado del trabajo te dice si obtuviste una traducción.
Cómo una falla en una etapa se convierte en una advertencia del trabajo#
Cuando falla una etapa no crítica, la falla aparece en dos lugares al mismo tiempo, y ambas son vistas del mismo evento. El registro de steps[] aparece como failed con un errorMessage; esa es la vista detallada. La misma falla también aparece como una entrada en el arreglo warnings de nivel superior del trabajo; esa es la vista resumida sobre la que se apoya tu código de manejo de estados:
{
"id": "ljb_A1b2C3d4E5f6G7h8",
"status": "completed_with_warnings",
"outputData": { "title": "Hallo" },
"warnings": [
{ "step": "backTranslation", "message": "Back-translation check did not complete" }
],
"steps": [
{ "stepId": "localize", "type": "action", "status": "completed", "errorMessage": null, "costUsd": 0.0184, "completedAt": "2026-03-16T10:30:05.000Z" },
{ "stepId": "backTranslation", "type": "action", "status": "failed", "errorMessage": "Back-translation check did not complete", "costUsd": 0.0031, "completedAt": "2026-03-16T10:30:11.000Z" }
]
}Cada entrada de warnings es { step, message }, donde step es el mismo stepId que encontrarías en el registro fallido. Así, los dos arreglos se alinean: warnings es la lista corta de lo que salió mal, y steps[] es donde vas para ver el detalle detrás de cada caso. Lee warnings para decidir si debes marcar el idioma para una revisión humana; lee el registro correspondiente de steps[] cuando quieras ver el errorMessage, el costo y los tiempos detrás de eso.
Ese es el mecanismo detrás de completed_with_warnings: la traducción central tuvo éxito, así que tienes un outputData utilizable, pero al menos una etapa no crítica dejó un registro failed y una advertencia correspondiente. Trata el resultado como apto para publicarse y las advertencias como una señal de calidad que vale la pena mostrar. Solo un status del trabajo de failed significa que no hay traducción para leer, y esa decisión, junto con la tabla completa de estados del trabajo, está en la página del trabajo individual.
La salud agregada de las etapas vive en otra superficie
steps[] responde a "¿qué hizo el pipeline en este trabajo?". Si quieres ver la tendencia a lo largo de muchos trabajos —con qué frecuencia falla pre-edit, con qué frecuencia back-translation corrige una traducción—, esa es una pregunta agregada y se responde en la página de Reports, no en una respuesta por trabajo. Aquí, registros por trabajo; allá, agregados.
