CSV por idioma

Traducción con IA para archivos CSV con archivos separados por idioma usando Lingo.dev CLI

¿Qué es CSV por idioma?

CSV por idioma es un enfoque de traducción donde cada idioma tiene su propio archivo CSV separado, en lugar de almacenar todos los idiomas en un único archivo CSV con múltiples columnas. Este formato es útil cuando tienes datos estructurados con múltiples columnas (como catálogos de productos, datos de usuarios o sistemas de gestión de contenido) donde cada fila representa un registro y las columnas representan diferentes campos.

Por ejemplo:

id,name,description,created,enabled,sort
1,Welcome,Welcome to our application,2024-01-01,true,1
2,Save,Save your changes,2024-01-01,true,2
3,Error,An error occurred,2024-01-01,true,3

A diferencia del bucket estándar CSV que almacena todos los idiomas en un archivo con columnas como KEY,en,es, el bucket csv-per-locale mantiene archivos separados para cada idioma, preservando la estructura CSV original con todas las columnas.

¿Qué es Lingo.dev CLI?

Lingo.dev CLI es una CLI gratuita y de código abierto para traducir aplicaciones y contenido con IA. Está diseñada para reemplazar el software tradicional de gestión de traducciones mientras se integra con los pipelines existentes.

Para obtener más información, consulta Descripción general.

Acerca de esta guía

Esta guía explica cómo traducir archivos CSV usando el bucket csv-per-locale con Lingo.dev CLI.

Aprenderás a:

  • Crear un proyecto desde cero
  • Configurar un pipeline de traducción con archivos CSV separados por idioma
  • Generar traducciones con IA
  • Usar claves bloqueadas e ignoradas

Requisitos previos

Para usar Lingo.dev CLI, asegúrate de tener instalado Node.js v18+:

❯ node -v
v22.17.0

Paso 1. Configurar un proyecto

En el directorio de tu proyecto, crea un archivo i18n.json:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

Este archivo define el comportamiento del pipeline de traducción, incluyendo qué idiomas traducir y dónde existe el contenido localizable en el sistema de archivos.

Para obtener más información sobre las propiedades disponibles, consulta i18n.json.

Paso 2. Configurar la configuración regional de origen

La configuración regional de origen es el idioma y la región originales en los que se escribió tu contenido. Para configurar la configuración regional de origen, establece la propiedad locale.source en el archivo i18n.json:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

La configuración regional de origen debe proporcionarse como una etiqueta de idioma BCP 47.

Para ver la lista completa de códigos de configuración regional que admite Lingo.dev CLI, consulta Códigos de configuración regional admitidos.

Paso 3. Configurar las configuraciones regionales de destino

Las configuraciones regionales de destino son los idiomas y regiones a los que deseas traducir tu contenido. Para configurar las configuraciones regionales de destino, establece la propiedad locale.targets en el archivo i18n.json:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

Paso 4. Crear el contenido de origen

Si aún no lo has hecho, crea un archivo CSV para tu configuración regional de origen. El archivo debe contener:

  • Una fila de encabezado con nombres de columnas
  • Una o más filas de datos
  • Cualquier columna que necesites (no limitado a nombres de columnas específicos)

El archivo CSV debe estar ubicado en una ruta que incluya la configuración regional de origen en algún lugar de la ruta (por ejemplo, como un nombre de directorio como en/ o como parte del nombre del archivo como data.en.csv).

Nota: A diferencia del bucket CSV estándar, no necesitas una columna "KEY" ni una columna que coincida con la configuración regional de origen. El bucket csv-per-locale trata cada fila como un registro y traducirá todo el contenido de texto en el CSV mientras preserva la estructura.

Paso 5. Crear un bucket

  1. En el archivo i18n.json, añade un objeto "csv-per-locale" al objeto buckets:

    {
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "csv-per-locale": {}
  }
}

  2. En el objeto "csv-per-locale", define un array de uno o más patrones include:

    {
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "csv-per-locale": {
      "include": ["./[locale]/example.csv"]
    }
  }
}

    Estos patrones definen qué archivos traducir.

    Los patrones en sí:

    • deben contener [locale] como marcador de posición para la configuración regional configurada
    • pueden apuntar a rutas de archivos (p. ej., "[locale]/data.csv")
    • pueden usar asteriscos como marcadores de posición comodín (p. ej., "[locale]/*.csv")

    No se admiten patrones glob recursivos (p. ej., **/*.csv).

  3. Opcionalmente, puedes configurar lockedKeys y ignoredKeys:

    {
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "csv-per-locale": {
      "include": ["./[locale]/example.csv"],
      "lockedKeys": ["locked_key_1"],
      "ignoredKeys": ["ignored_key_1"]
    }
  }
}
    • lockedKeys: claves (valores de columna en la primera columna, normalmente un ID) que no deben traducirse
    • ignoredKeys: claves que no deben aparecer en los archivos de configuración regional de destino

Paso 6. Configurar un LLM

Lingo.dev CLI utiliza modelos de lenguaje de gran tamaño (LLM) para traducir contenido con IA. Para usar uno de estos modelos, necesitas una clave API de un proveedor compatible.

Para empezar lo más rápido posible, recomendamos usar Lingo.dev Engine, nuestra propia plataforma alojada que ofrece 10 000 tokens de uso gratuito mensual:

  1. Regístrate para obtener una cuenta de Lingo.dev.

  2. Ejecuta el siguiente comando:

    npx lingo.dev@latest login

    Esto abrirá tu navegador predeterminado y te pedirá que te autentiques.

  3. Sigue las instrucciones.

Paso 7. Generar las traducciones

En el directorio que contiene el archivo i18n.json, ejecuta el siguiente comando:

npx lingo.dev@latest run

Este comando:

  1. Lee el archivo i18n.json.
  2. Encuentra los archivos que necesitan ser traducidos.
  3. Extrae el contenido traducible de los archivos CSV.
  4. Utiliza el LLM configurado para traducir el contenido extraído.
  5. Escribe el contenido traducido en archivos CSV separados para cada locale de destino.

La primera vez que se generan las traducciones, se crea un archivo i18n.lock. Este archivo realiza un seguimiento del contenido que ha sido traducido, evitando retraducciones innecesarias en ejecuciones posteriores.

Ejemplo

en/example.csv (antes de la traducción)

id,name,description,created,enabled,sort
1,Welcome,Welcome to our application,2024-01-01,true,1
2,Save,Save your changes,2024-01-01,true,2
3,Error,An error occurred,2024-01-01,true,3
4,Success,Operation completed successfully,2024-01-01,true,4
5,Loading,Please wait while we load your data,2024-01-01,true,5

es/example.csv (después de la traducción)

id,name,description,created,enabled,sort
1,Bienvenida,Bienvenido a nuestra aplicación,2024-01-01,true,1
2,Guardar,Guarda tus cambios,2024-01-01,true,2
3,Error,Ha ocurrido un error,2024-01-01,true,3
4,Éxito,Operación completada con éxito,2024-01-01,true,4
5,Cargando,Por favor espera mientras cargamos tus datos,2024-01-01,true,5

i18n.json

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "csv-per-locale": {
      "include": ["./[locale]/example.csv"],
      "lockedKeys": ["locked_key_1"],
      "ignoredKeys": ["ignored_key_1"]
    }
  }
}

i18n.lock

version: 1
checksums:
  e8b273672f895de0944f0a2317670d7c:
    0/name: 1308168cca4fa5d8d7a0cf24e55e93fc
    0/description: 8de4bc8832b11b380bc4cbcedc16e48b
    1/name: f7a2929f33bc420195e59ac5a8bcd454
    1/description: 8de4bc8832b11b380bc4cbcedc16e48b
    2/name: d3d99b147cc363dc6db8a48e8a13d4c1
    2/description: 7cd986af1fe5e89abe7ecffba5413110

Diferencias con el bucket CSV

El bucket csv-per-locale difiere del bucket estándar csv en varios aspectos:

  • Estructura de archivos: csv-per-locale utiliza archivos separados para cada locale (por ejemplo, en/example.csv, es/example.csv), mientras que csv utiliza un único archivo con múltiples columnas (por ejemplo, KEY,en,es).

  • Requisitos de columnas: csv-per-locale no requiere una columna "KEY" ni columnas con nombres de locales. Puedes utilizar cualquier estructura de columnas que se ajuste a tus datos.

  • Casos de uso: csv-per-locale es ideal para datos estructurados como catálogos de productos, sistemas de gestión de contenidos o bases de datos donde cada fila representa un registro con múltiples campos. El bucket estándar csv es más adecuado para tablas de traducción simples de clave-valor.

  • Mutaciones de archivos: Ambos buckets mutan archivos directamente, pero csv-per-locale crea archivos separados para cada locale, mientras que csv añade nuevas columnas al archivo existente.