Traducción humana

No toda cadena es para un proveedor. Los textos de marketing, los textos legales y los idiomas que más importan suelen pedir un traductor humano. verbatra lo resuelve con un ciclo de ida y vuelta de un libro: exporta las cadenas que necesitan traducción a un archivo de Excel con estilos, entrégalo, y luego importa el archivo rellenado de vuelta a tus archivos de locale.

El mismo diff impulsa ambas direcciones. La exportación elige exactamente las claves que una ejecución automática traduciría (las nuevas y las modificadas), y la importación ejecuta las mismas comprobaciones de marcadores de posición e ICU que translate, así que un valor escrito a mano que rompe un marcador de posición se retiene y se informa en lugar de escribirse.

El ciclo de ida y vuelta

# 1. Export the strings that need translating
verbatra export

# 2. A translator fills the Translation column and sends the file back

# 3. Import the filled workbook
verbatra import verbatra-translations.xlsx

Por defecto, la exportación escribe verbatra-translations.xlsx en el directorio de trabajo. La importación lo lee de vuelta, valida cada fila rellenada, escribe en tus archivos de locale los valores que pasan y avanza la línea base de el archivo de bloqueo exactamente para las claves que aceptó, igual que lo haría una ejecución de translate.

Qué acaba en el libro

El archivo abre con una hoja Instructions, seguida de una hoja de datos por locale de destino, nombrada por su locale (de, fr, ...). Como el locale hace el viaje de ida y vuelta a través del nombre de la hoja, un locale que no puede ser un nombre de hoja de Excel se rechaza antes de construir el libro: más largo de 31 caracteres, que contenga cualquiera de : \ / ? * [ ], igual a Instructions en cualquier combinación de mayúsculas, o igual a otro locale de destino sin distinguir mayúsculas.

Todas las hojas de datos comparten las mismas columnas, en este orden:

Las filas están ordenadas por clave, la fila de encabezado está inmovilizada, la columna Source hash está oculta y todas las columnas excepto Translation están bloqueadas con protección de hoja y un fondo sombreado. La columna Translation usa el formato de texto de Excel, así que un valor como 007 o uno que empieza por = se queda como texto literal en lugar de convertirse en un número o una fórmula.

La entrega

Lo que un traductor necesita saber cabe en unas pocas líneas (y se repite en la propia hoja Instructions del libro):

• Rellena la columna Translation, nada más. La protección de hoja lo impone.
• No renombres, borres ni reordenes las pestañas de idioma. verbatra empareja cada pestaña con un locale por su nombre exacto, así que una pestaña renombrada o ausente se informa y ese locale no se importa.
• Ordenar y filtrar filas está bien: la importación asigna las filas por Key, nunca por posición. Las columnas deben quedarse donde están; la importación las lee por posición y verifica los encabezados Key y Source hash.
• Una celda Translation vacía significa "todavía sin traducir". La importación la omite y nunca escribe una cadena vacía, así que un libro a medio rellenar puede volver ahora y el resto más tarde. Una celda que solo contiene espacios cuenta como vacía. Para vaciar deliberadamente un valor existente (dejarlo vacío), escribe exactamente [[CLEAR]] en la celda.

Qué acepta la importación

La importación no es un pegado a ciegas. Cada fila rellenada se juzga contra el proyecto vivo antes de escribir nada:

• Desfase del origen: el Source hash oculto se compara con el origen actual. Si la cadena de origen cambió después de la exportación, la fila se retiene, así que nunca sobrescribes un origen actual con la traducción de uno antiguo.
• Integridad de marcadores de posición: la traducción debe llevar exactamente los mismos marcadores de posición que su origen. Elimina {name} o inventa {total} y la fila se retiene.
• Validez ICU: un mensaje ICU debe seguir siendo estructuralmente válido con los mismos nombres de argumento; solo el texto legible puede cambiar.
• Claves desconocidas: una fila rellenada cuya clave no existe ni en el origen actual ni en el archivo de destino actual (por ejemplo, una escrita a mano) hace fallar la hoja entera de ese locale, porque el ciclo de ida y vuelta está roto. Una fila rellenada cuya clave existe solo en el destino (una clave huérfana) se deja sin escribir en silencio.
• Context nunca es una fuente de traducción: la importación ignora la columna Context por completo, y un libro exportado antes de que esa columna existiera sigue importándose con normalidad.

Las filas retenidas se informan en el resumen de la ejecución bajo el locale al que pertenecen; las filas aceptadas se escriben y su línea base del bloqueo avanza. Una fila retenida o en blanco conserva su línea base anterior, así que la clave se sigue exportando hasta que se resuelve de verdad. Una fila en blanco cuyo origen se desfasó desde la exportación se señala además con un aviso BLANK_ROW_BASELINE_RETAINED, para que el desfase siga visible.

La importación también expone hallazgos estructurales por locale en lugar de abortar por ellos: una fila changed que el traductor dejó en blanco (informada como unfilled, aún pendiente), una fila del libro que el lector no pudo parsear (informada por fila y columna) y una clave duplicada (la primera aparición gana y se importa, cada una posterior se informa). Ninguno de estos hallazgos hace fallar la hoja por sí solo.

Cada hoja de datos es un locale en el resumen: un fallo de hoja (una clave inventada, una hoja de un locale que no está en tu configuración, o un locale configurado cuya pestaña falta por completo porque se renombró, se borró o se sacó de su orden) hace fallar ese locale y deja los demás intactos. La importación comparte el contrato de códigos de salida de translate: 0 cuando todas las hojas tienen éxito, 1 cuando una falla, 2 cuando la ejecución no pudo arrancar. Una entrega manual encaja por tanto en las mismas comprobaciones de CI que una ejecución automática.

Primero en seco

Valida un libro devuelto y previsualiza lo que se escribiría sin tocar un solo archivo:

verbatra import verbatra-translations.xlsx --dry-run

Seleccionar qué exportar

Por defecto, la exportación incluye solo las cadenas faltantes y modificadas, el trabajo que de verdad hay que hacer:

# Only the German and French sheets
verbatra export --locales de,fr

# Also include strings that are already up to date
verbatra export --include-unchanged

# Write to a specific path
verbatra export --out handoff/round-2.xlsx

Recurre a --include-unchanged cuando un traductor quiera el contexto completo de un locale, no solo el delta. Consulta verbatra export para todos los flags.

Las columnas de revisión

Review status y Review reasons son una capa no bloqueante encima de las comprobaciones de arriba: las heurísticas de verbatra para detectar una traducción estructuralmente correcta pero que merece una segunda mirada. Nunca retienen una fila y la importación nunca las lee; la única forma de limpiar una señal es corregir la traducción. Ambas columnas se recalculan al exportar a partir del origen y de los valores de destino actuales:

• length-ratio-outlier: la traducción es mucho más corta o más larga que su origen.
• equals-source: la traducción es idéntica al origen.
• glossary-term-missed: un término del glosario configurado no llegó a la traducción.
• integrity-reordered: los marcadores de posición coinciden pero quedaron en un orden distinto al del origen.

Un quinto motivo, provider-degraded, existe solo al traducir (un aviso de degradación de DeepL sobre el lote del que vino una clave); como la exportación nunca llama a un proveedor, nunca aparece en una fila exportada. Una fila todavía sin traducción siempre exporta ok; no hay nada que revisar. Consulta Seguridad de la traducción para ver cómo se relacionan estas señales con las comprobaciones duras de marcadores de posición e ICU.

Desde el SDK

Los comandos de la CLI envuelven dos funciones del SDK, exportWorkbook e importWorkbook:

import { exportWorkbook, importWorkbook, loadConfig } from "@verbatra/sdk";

const config = await loadConfig();

// Write a workbook of the strings that need translating
await exportWorkbook({ config });

// ...later, import the filled file back
const summary = await importWorkbook({ config, workbook: "verbatra-translations.xlsx" });

Ambas toman la configuración validada de loadConfig, e importWorkbook devuelve el mismo RunSummary que translate. El libro en sí lo construye y lo analiza @verbatra/exchange, un paquete interno al que solo llegas a través de estas dos funciones.

Siguientes pasos

• verbatra export: todos los flags de exportación y el informe que imprime.
• verbatra import: todos los flags de importación, el resumen de la ejecución y los códigos de salida.
• Seguridad de la traducción: las comprobaciones de marcadores de posición e ICU que protegen cada escritura, manual o automática.