CSV

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

Una tabla de traducción CSV guarda el texto de origen y todas las traducciones en un solo archivo: una fila por mensaje y una columna por idioma. El gestor de archivos csv completa las celdas de los idiomas de destino y guarda el resultado en la ruta de origen. Solo escribe en las celdas de los idiomas de destino y agrega una columna si un idioma no tiene una, como se explica en Qué filas se traducen. Las demás columnas, el orden de las filas, el uso de comillas y los finales de línea se mantienen intactos. La marca de orden de bytes UTF-8 al inicio del archivo no se conserva: el archivo se guarda sin ella. Por eso, si una aplicación de hojas de cálculo depende de esa marca para detectar UTF-8, puede ser necesario 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 el encabezado. 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 encabezado coincide con el código de ese idioma, sin distinguir entre mayúsculas y minúsculas: tanto de como DE identifican la columna de alemán, pero de-DE corresponde a otro idioma. El encabezado de la columna de origen es el sourceLocale de tu configuración.
  • Columna de clave. De forma predeterminada, la primera celda del encabezado define el nombre de la columna de clave. Configura keyColumn en la entrada del archivo para usar otra columna. La columna de origen también 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. Cada comilla dentro de ella se escribe dos veces (""). No se admiten archivos separados por punto y coma o 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 infiere el formato, o que establezca "format": "csv". Una entrada con "format": "csv" selecciona únicamente archivos .csv. Un patrón amplio como data/**/* sin ese formato nunca selecciona archivos CSV, lo que evita que una entrada existente empiece a reescribir archivos de datos no relacionados. 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 mismo archivo sirve como destino para todos los idiomas, por lo que targetPath no se admite en este formato. Las filas CSV no se comparan 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 cuyas celdas estén vacías o desactualizadas.
Clave, celda de origen vacíaSe conserva tal como está; sus celdas de idioma no se modifican.
Texto de origen, celda de clave vacía o con solo espaciosSe conserva tal como está y no se traduce. Asígnale una clave para traducirla.
Clave y origen vacíos, o una 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 agregada 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 nueva. Las celdas con contenido también se conservan en el primer envío del archivo, al usar --force de 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 cual comparar, por ejemplo, después de cambiarle el nombre a una de ellas. Un comando de la GitHub App con --force vuelve a traducir todas las filas del archivo.

Los siguientes tipos de texto de origen se copian en lugar de traducirse: texto compuesto únicamente por dígitos ASCII del 0 al 9, como 100; una URL que empieza con // o tiene un esquema formado por letras, dígitos o guiones bajos seguido de ://, y cuya dirección después de // empieza con localhost o contiene al menos un carácter, un punto y al menos dos caracteres más, como https://lingo.dev/docs; un ID de 22 caracteres formado únicamente por letras y dígitos, con al menos una letra mayúscula, una letra minúscula y un dígito; y una fecha o una fecha y hora 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 esa fila y reemplaza su contenido. La fila no se envía a traducción 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 con localhost ni contiene un punto que cumpla esas condiciones, como https://intranet o https://a.b.

Si un idioma de destino no tiene una columna, se agrega al final del encabezado. Si se agregan varias columnas, se ordenan alfabéticamente por sus códigos de idioma. Luego se completa cada fila con celdas vacías para mantener la tabla rectangular. Las filas nunca se reordenan, agregan ni eliminan.

Errores #

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

  • el keyColumn configurado no aparece en el encabezado, o la primera celda del encabezado está vacía y no se ha configurado keyColumn;
  • dos filas tienen la misma clave, porque sus traducciones quedarían en las filas incorrectas;
  • el encabezado no tiene una columna para el idioma de origen;
  • la columna de clave también es la columna de un idioma de destino;
  • el encabezado 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 el encabezado;
  • una celda entre comillas no tiene comilla de cierre;
  • hay texto después de una comilla 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 comprobación.

Corrige una traducción existente #

Para cambiar la redacción de forma precisa, edita la celda. Para regenerar una traducción, vacía esa celda, conserva el resto de la fila y ejecuta un envío normal:

sh
lingo push --wait

--force de la CLI 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.