CSV

Traduce una tabla CSV con una columna por idioma en un único archivo y la columna que elijas como clave.

Una tabla de traducción CSV reúne el texto de origen y todas las traducciones en un único archivo: una fila por mensaje y una columna por idioma. El controlador de archivos csv rellena las celdas de los idiomas de destino y guarda el resultado en la ruta de origen. Solo modifica esas celdas y añade una columna cuando un idioma no tiene ninguna, como se explica en Qué filas se traducen. Las demás columnas, el orden de las filas, las comillas y los finales de línea se mantienen intactos. La marca de orden de bytes UTF-8 al principio del archivo no se conserva: el archivo se guarda sin ella. Por eso, si una aplicación de hojas de cálculo utiliza esa marca para detectar UTF-8, puede que tengas que importar el archivo como UTF-8.

Organiza la tabla #

La primera línea que no esté vacía ni contenga solo espacios en blanco es la cabecera. Una columna contiene la clave que identifica cada fila, otra contiene el texto de origen y cada idioma de destino tiene su propia columna:

csv
id,en,notes,de
checkout.title,Complete your order,Shown on the last step,Bestellung abschließen
checkout.pay,"Pay now, or later",,
  • Columnas de idioma. Una columna corresponde a un idioma cuando su cabecera coincide con el código de ese idioma, sin distinguir entre mayúsculas y minúsculas: de y DE identifican la columna de alemán, pero de-DE corresponde a un idioma distinto. La cabecera de la columna de origen es el valor de sourceLocale de tu configuración.
  • Columna de clave. Por defecto, la primera celda de la cabecera da nombre a la columna de clave. Define keyColumn en la entrada del archivo para usar otra columna. La propia columna de origen puede servir como columna de clave si el texto de origen es la clave.
  • Otras columnas. Las columnas que no corresponden ni a la clave ni a un idioma, como notes, se conservan byte por byte y nunca se envían a traducir.
  • Sintaxis. Las celdas se separan con comas. Si una celda contiene una coma, una comilla o un salto de línea, se encierra entre comillas dobles. Las comillas que aparezcan dentro se duplican (""). No se admiten archivos separados por punto y coma ni por tabulaciones.

Configura la traducción de CSV #

Un archivo CSV solo se selecciona mediante una entrada de archivos cuyo patrón termine en .csv, en cuyo caso se deduce el formato, o que especifique "format": "csv". Una entrada con "format": "csv" solo selecciona archivos .csv. Un patrón amplio como data/**/*, sin ese formato, nunca selecciona archivos CSV. Así, una entrada existente no empieza a reescribir archivos de datos que no le corresponden. La extensión distingue entre mayúsculas y minúsculas: un archivo llamado strings.CSV no se traduce, así que cámbiale el nombre a strings.csv.

json
{
  "sourceLocale": "en",
  "targetLocales": ["de", "fr"],
  "files": [{ "pattern": "i18n/strings.csv", "keyColumn": "id" }]
}

El propio archivo es el destino de todos los idiomas, por lo que targetPath no se admite en este formato. Las filas CSV no se cotejan con los controles de claves, así que tampoco se admiten lockedKeys, preservedKeys ni ignoredKeys. La misma configuración funciona en la CLI y en la GitHub App.

Qué filas se traducen #

FilaResultado
Clave y texto de origenSe traduce en los idiomas cuya celda esté vacía o desactualizada.
Clave y celda de origen vacíaSe conserva tal como está; sus celdas de idioma no se modifican.
Texto de origen y celda de clave vacía o solo con espaciosSe conserva tal como está y no se traduce. Asígnale una clave para traducirla.
Clave y texto de origen vacíos, o línea en blancoSe conserva tal como está, incluso si la línea solo contiene espacios.

Una celda de idioma que solo contiene espacios se considera vacía. Una celda con contenido se reutiliza si el texto de origen de su fila no ha cambiado desde el último envío. Cuando cambia el texto de origen de una fila, se vuelven a traducir todas sus celdas de idioma. Una fila añadida desde el último envío conserva las celdas con contenido y solo se traducen las vacías; si cambia la clave de una fila, se considera una fila añadida. Las celdas con contenido también se conservan en el primer envío del archivo, al usar --force en la CLI, al ejecutar un comando de la GitHub App que especifique archivos sin --force y cuando el archivo enviado anteriormente no tenga una única columna de origen o de clave con la que comparar, por ejemplo, después de cambiar el nombre de una de ellas. Un comando de la GitHub App con --force vuelve a traducir todas las filas del archivo.

Los siguientes textos de origen se copian en lugar de traducirse: los que contienen solo dígitos ASCII del 0 al 9, como 100; las URL que empiezan por // o cuyo esquema está formado por letras, dígitos o guiones bajos seguidos de ://, y cuya dirección después de // empieza por localhost o contiene al menos un carácter, un punto y al menos dos caracteres más, como https://lingo.dev/docs; los ID de 22 caracteres formados solo por letras y dígitos, con al menos una letra mayúscula, una letra minúscula y un dígito; y las fechas o fechas y horas en formato ISO 8601, como 2024-01-15 o 2024-01-15T10:00:00Z. El texto de origen se copia en todas las celdas de los idiomas de destino de su fila y sustituye el contenido de cada una. La fila no se envía a traducir ni se factura. Otros valores, como 1.5, 100%, una dirección de correo electrónico o una fecha en otro formato, como 15.01.2024, sí se traducen. También se traducen los enlaces mailto: y tel:, las URL cuyo esquema contiene otros caracteres, como git+ssh://, y las URL cuya dirección no empieza por localhost ni contiene un punto que cumpla las condiciones descritas, como https://intranet o https://a.b.

Si un idioma de destino no tiene columna, se añade una al final de la cabecera. Si hay varias columnas nuevas, se añaden en orden alfabético según sus códigos de idioma. Después, cada fila se completa con celdas vacías para mantener la tabla rectangular. Las filas nunca se reordenan, añaden ni eliminan.

Errores #

El procesamiento del archivo falla antes de traducir o facturar nada, y el mensaje indica el problema, cuando:

  • el keyColumn configurado no aparece en la cabecera, o la primera celda de la cabecera está vacía y no se ha definido keyColumn;
  • dos filas tienen la misma clave, ya que sus traducciones acabarían en las filas equivocadas;
  • la cabecera no tiene ninguna columna para el idioma de origen;
  • la columna de clave también es la de un idioma de destino;
  • la cabecera incluye más de una vez el keyColumn configurado, el idioma de origen o un idioma de destino;
  • una fila tiene más celdas que la cabecera;
  • una celda entre comillas no tiene comillas de cierre;
  • hay texto después de las comillas de cierre en la misma celda.

Corrige el archivo y vuelve a enviarlo. La CLI muestra el mensaje una sola vez debajo del archivo, no una vez por idioma. Si falla toda la ejecución, la línea final Run failed: repite el mensaje. La GitHub App lo muestra en la ejecución de la comprobación.

Corrige una traducción existente #

Para hacer un cambio concreto en la redacción, edita la celda. Para regenerar una traducción, vacía esa celda, deja el resto de la fila como está y ejecuta un envío sin opciones adicionales:

sh
lingo push --wait

En la CLI, --force reutiliza las celdas con contenido, igual que con los catálogos de cadenas de Apple. --key no limita el alcance de un archivo CSV: la CLI detiene el envío con un error y la GitHub App omite el archivo. La purga de la CLI omite el archivo porque el origen y la salida comparten la misma ruta. Revisa todas las diferencias del archivo antes de confirmar los cambios.