Extracción de claves i18n con IA

Convertir una aplicación React existente para que admita múltiples idiomas es a veces un proceso tedioso que consiste en encontrar cadenas de texto codificadas y reemplazarlas con claves de traducción.

Lingo.dev CLI funciona perfectamente con IDEs potenciados por IA como Cursor, GitHub Copilot y herramientas similares para automatizar la extracción de contenido traducible de tus componentes React.

El concepto explicado a continuación puede utilizarse para cualquier stack tecnológico, pero para simplificar y demostrar la idea, utilizaremos una aplicación React de tipo "hola mundo" como ejemplo.

Requisitos previos

Antes de extraer las claves, configura la internacionalización básica en tu aplicación React. Para obtener instrucciones completas de configuración, consulta la documentación de react-intl.

Después de seguir la configuración de internacionalización para tu stack tecnológico, tu proyecto debería tener:

  • Capacidad para cambiar dinámicamente entre idiomas en la aplicación
  • Estructura básica del proyecto para organizar archivos de traducción

Proceso de configuración

Instala y configura Lingo.dev CLI:

npx lingo.dev@latest init

Crea un archivo fuente vacío:

mkdir -p src/locales
echo '{}' > src/locales/en.json

Configura i18n.json:

{
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de"]
  },
  "buckets": {
    "json": {
      "include": ["src/locales/[locale].json"]
    }
  }
}

Extracción de claves con IA

Selecciona tu componente React y utiliza tu IDE con IA para extraer las cadenas de texto codificadas:

Antes de la extracción:

function WelcomeCard() {
  return (
    <div className="card">
      <h2>Welcome to our platform</h2>
      <p>Start your journey with us today</p>
      <button>Get started</button>
    </div>
  );
}

Requisitos para la extracción:

  1. Reemplazar las cadenas de texto codificadas con hooks y componentes de react-intl
  2. Utilizar el formato ICU para variables y plurales
  3. Estructurar las claves jerárquicamente según la organización de componentes
  4. Añadir todas las claves al archivo JSON fuente
  5. Mantener convenciones de nomenclatura consistentes

Prompt para la IA:

Extrae todas las cadenas de texto codificadas de los componentes React y:

1. Reemplázalas con react-intl:
   - Utiliza el hook useIntl para cadenas dinámicas
   - Utiliza FormattedMessage para texto estático
   - Añade formato ICU para variables ({name}) y plurales ({count})

2. Estructura las claves de traducción:
   - Agrupa por jerarquía de componentes (components.*, pages.*)
   - Utiliza claves descriptivas y anidadas (header.nav.home)
   - Haz coincidir la estructura de componentes en JSON

3. Actualiza los archivos de idioma:
   - Añade todas las claves a src/locales/en.json
   - Mantén una nomenclatura consistente en toda la aplicación

Después de la extracción con IA:

import { useIntl } from "react-intl";

function WelcomeCard() {
  const intl = useIntl();

  return (
    <div className="card">
      <h2>{intl.formatMessage({ id: "welcome.title" })}</h2>
      <p>{intl.formatMessage({ id: "welcome.description" })}</p>
      <button>{intl.formatMessage({ id: "welcome.getStarted" })}</button>
    </div>
  );
}

Archivo en.json generado:

{
  "welcome.title": "Welcome to our platform",
  "welcome.description": "Start your journey with us today",
  "welcome.getStarted": "Get started"
}

Procesamiento por lotes

Para múltiples componentes, selecciona todos los archivos y utiliza el mismo prompt integral. Los IDE con IA como Cursor, GitHub Copilot y otros pueden procesar múltiples archivos simultáneamente, manteniendo una nomenclatura de claves consistente en toda tu aplicación.

Generación de traducciones

Una vez que tu IDE con IA extraiga las claves, genera las traducciones:

npx lingo.dev@latest i18n

Esto crea versiones traducidas de tu archivo fuente:

src/locales/
  en.json    (fuente con claves extraídas)
  es.json    (traducciones al español)
  fr.json    (traducciones al francés)
  de.json    (traducciones al alemán)

Validación

Después de la extracción, verifica tu configuración:

Comprueba la cobertura de traducción:

npx lingo.dev@latest i18n --frozen

Este comando falla si falta alguna traducción, asegurando una cobertura completa.

Prueba con diferentes locales:

// Cambia el locale en tu aplicación para verificar que las traducciones funcionan
<IntlProvider locale="es" messages={spanishMessages}>
  <WelcomeCard />
</IntlProvider>