Localiza una aplicación web
Conecta los catálogos traducidos con la selección de idioma, la carga de recursos y las comprobaciones de renderizado de tu framework.
Si tu aplicación web ya renderiza mensajes a partir de archivos de idioma, mantén esa configuración. Lingo.dev puede traducir los catálogos de origen mientras la biblioteca que ya utilizas sigue seleccionando el idioma, cargando los mensajes y renderizándolos. Completa este ciclo en una pantalla antes de traducir el resto de la aplicación.
Esta guía explica cómo trabajar con catálogos existentes basados en claves en distintos frameworks. Para mensajes basados en texto de origen y contexto con @lingo.dev/react, consulta la guía de inicio rápido de React o la guía de migración. Los identificadores extraídos con este enfoque son distintos de las claves de un catálogo existente de i18next o next-intl.
Prepara un caso de prueba de principio a fin #
Elige una pantalla que incluya una etiqueta, un mensaje con una variable y otro con plurales o condiciones. Renderízala en el idioma de origen con la biblioteca que ya utilizas. Conserva sus espacios de nombres, su sintaxis de interpolación y sus claves de consulta: una traducción genérica de JSON no convierte la gramática de mensajes de una biblioteca en la de otra.
Si ya tienes un archivo de origen de react-i18next en public/locales/en/translation.json, inicializa la CLI desde la raíz del proyecto:
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es --files 'public/locales/en/translation.json' --yes
lingo linkEl archivo .lingo/config.json vinculado debe tener esta estructura:
{
"orgId": "org_...",
"engineId": "eng_...",
"sourceLocale": "en",
"targetLocales": ["es"],
"files": [{ "pattern": "public/locales/en/translation.json" }]
}Conserva los identificadores reales de la organización y del motor de localización obtenidos al realizar la vinculación. Si utilizas otro framework, sustituye la ruta de origen por la que se indica en las secciones siguientes. Selecciona únicamente los catálogos de origen y ajusta la ruta de destino a la que utiliza el cargador. Usa rutas de destino explícitas para estructuras sin un segmento de idioma.
Traduce los destinos que faltan con:
lingo push --backfill-missing --waitCuando termine el proceso, inspecciona el catálogo generado y carga la pantalla en español. Compara los mismos valores de variables y casos de plural en ambos idiomas. El paso específico de cada framework que encontrarás más abajo conecta ese archivo con la petición o la compilación real. Un primer envío sin opciones adicionales puede guardar una versión de referencia sin solicitar las traducciones que faltan.
No modifiques los archivos de destino mientras esperas a que se escriban los resultados. Si necesitas proteger las correcciones locales existentes frente a conflictos, envía sin --wait, inspecciona lingo pull --dry-run y recupera después los resultados en el checkout desde el que hiciste el envío. Consulta Conservar las traducciones revisadas.
React con react-i18next #
Con react-i18next, conserva los espacios de nombres y las llamadas de consulta que ya utilizas. Un archivo de origen en public/locales/en/translation.json se corresponde con public/locales/es/translation.json. Si la aplicación utiliza varios espacios de nombres, configura cada archivo de origen en inglés en lugar de usar un patrón glob que también incluya los archivos generados en español.
Configura el cargador de recursos de i18next para que solicite el idioma y el espacio de nombres de destino. Después, utiliza las llamadas useTranslation existentes para renderizar el caso de prueba. Comprueba la sustitución de variables y la convención de claves de plural de la versión de i18next que tengas instalada. Un traductor genérico de JSON no convierte el esquema de plurales de una biblioteca en el de otra. En una aplicación cliente, inspecciona tanto la petición de red del recurso como el texto visible: el uso del inglés como idioma alternativo puede ocultar que falta un archivo en español.
App Router de Next.js con next-intl #
Con next-intl, un archivo de origen habitual es messages/en.json, a partir del cual se genera messages/es.json. Configura la resolución del idioma al procesar la petición y carga los mensajes correspondientes en la configuración de next-intl. Mantén las rutas y la navegación por idioma coherentes con esa elección.
Renderiza el caso de prueba tanto mediante una petición directa en el idioma de destino como navegando desde otro idioma. Comprueba el contenido renderizado en el servidor, la hidratación en el cliente y las variables o los plurales de ICU. Traducir el archivo de mensajes no añade por sí solo un segmento de idioma a App Router ni un selector de idioma. Para documentos extensos que acompañen a estos catálogos de interfaz, utiliza Markdoc con Next.js.
Pages Router de Next.js con next-i18next #
Con next-i18next, ajusta el patrón de origen al directorio de idiomas y los espacios de nombres que ya utilizas. Si son public/locales/en/common.json y public/locales/en/checkout.json, traduce ambos a sus archivos equivalentes en español. Si utilizas messages/en.json, conserva el cargador personalizado que realmente lo carga.
Carga los espacios de nombres necesarios mediante el mecanismo de carga de datos que ya utiliza la página, ya sea en el servidor o de forma estática. Verifica una petición directa a la página localizada y un cambio de ruta en el cliente. Comprueba que los datos iniciales de la página y el entorno de ejecución del cliente coincidan en el idioma y el espacio de nombres: tener un archivo traducido en disco no basta si la página nunca lo incluye.
Vue con vue-i18n #
vue-i18n puede cargar diccionarios como src/locales/en.json y src/locales/es.json. Traduce el archivo de origen en inglés y registra o carga dinámicamente el diccionario en español en la instancia de i18n existente. Establece el idioma seleccionado en el punto donde tu aplicación ya lo gestiona.
Ejecuta las llamadas $t o useI18n en el caso de prueba. Comprueba las claves anidadas, la interpolación y la sintaxis de los mensajes en plural de la biblioteca instalada. Prueba tanto un cambio de idioma sin recargar como una carga de la página desde cero. Si los diccionarios se incorporan mediante importaciones, confirma que el archivo traducido se incluye en la compilación.
Nuxt con el módulo i18n #
Con Nuxt i18n, traduce un archivo de origen como locales/en.json a locales/es.json. Registra el idioma y el archivo en la configuración del módulo correspondiente a la versión que tengas instalada. Asegúrate de que el directorio de idiomas configurado coincida con la ruta de salida de la CLI.
Sigue la estrategia de rutas por idioma del proyecto en lugar de crear otra en la tarea de traducción. Verifica el renderizado en el servidor, la carga diferida, la navegación localizada y los metadatos en la página de prueba. Añadir un idioma de destino a la configuración de traducción no lo incorpora por sí solo a la lista de idiomas de Nuxt.
Diccionarios de Svelte y SvelteKit #
Con svelte-i18n, traduce un diccionario como src/lib/locales/en.json. Registra el diccionario de destino o su cargador diferido e inicializa el idioma seleccionado antes de que el componente lo necesite.
Renderiza el caso de prueba mediante el almacén de traducciones que ya utiliza la aplicación. Si la aplicación usa SSR, prueba una nueva petición con renderizado en el servidor y, después, un cambio de idioma en el cliente. Comprueba que cada petición al servidor tenga su propio estado de idioma y que el diccionario de destino termine de cargarse. No tomes el contenido alternativo como prueba de que la traducción se ha completado.
XLIFF de Angular #
Utiliza el flujo de trabajo de i18n de Angular para marcar y extraer primero los mensajes. El procesador de XLIFF admite XLIFF 1.2 y 2.x, tanto texto sin formato como códigos en línea. El texto dentro de códigos emparejados como <g> y <pc> se traduce conservando su estructura; los códigos independientes como <ph> permanecen protegidos. Mantén estables los identificadores de los mensajes y los códigos en línea e inspecciona los marcadores de posición devueltos antes de importar el catálogo de destino.
Para las entradas compatibles, src/locale/en/messages.xlf se corresponde con src/locale/es/messages.xlf. XLIFF no utiliza la sustitución de sufijos de messages.en.xlf a messages.es.xlf; utiliza el directorio del idioma o una plantilla de destino explícita. Conserva los identificadores de los mensajes al devolver las traducciones a Angular.
Registra el archivo de destino en la configuración de compilación para la localización de Angular, compila el paquete del idioma de destino y sírvelo para inspeccionar la pantalla. La localización de Angular en tiempo de compilación funciona de forma distinta a un cargador JSON en tiempo de ejecución: cambiar el idioma del navegador no genera un paquete localizado que falta. Comprueba la cobertura de los mensajes y el renderizado de los marcadores de posición antes de aceptar el paquete.
Astro #
Para las etiquetas de la interfaz, traduce src/i18n/en.json a su archivo equivalente de destino y configura tu propio cargador de diccionarios para que lo seleccione. Para las colecciones de contenido, traduce los archivos de origen Markdown o MDX de cada idioma y utiliza el flujo de trabajo de contenido estático.
Configura el enrutamiento por idioma de Astro de forma independiente de la traducción. Compila y visita las rutas de destino generadas. Comprueba los enlaces entre las versiones en distintos idiomas y las islas de cliente que carguen sus propios mensajes. Una colección de contenido y el diccionario de interfaz de una isla pueden necesitar entradas independientes.
Laravel #
Para la localización de Laravel, un archivo de origen PHP como lang/en/messages.php se corresponde con lang/es/messages.php. Conserva las claves de los arrays y los nombres de las sustituciones en tiempo de ejecución. Consulta la referencia del formato PHP antes de seleccionar archivos que contengan código ejecutable fuera de la estructura de catálogo admitida.
Establece el idioma de la petición mediante el middleware que ya utiliza la aplicación o la política del controlador, y renderiza los mensajes con las funciones auxiliares de traducción de Laravel. Prueba los valores de sustitución y la selección de plurales. Prueba una petición en cada idioma admitido y un caso en el que se recurra al idioma alternativo: los archivos traducidos no seleccionan el idioma de la petición.
Django #
Utiliza el flujo de trabajo de extracción de Django para crear locale/en/LC_MESSAGES/django.po y después traduce ese archivo PO de origen al directorio del idioma de destino. Conserva los identificadores de los mensajes de gettext, el contexto y la interpolación. Compila el PO traducido para generar el recurso que Django carga realmente, mediante el paso de compilación de gettext que ya utiliza el proyecto.
Configura la selección de idioma de Django y la lista de idiomas. Verifica una petición localizada a través del middleware de traducción y renderiza los mensajes mediante llamadas en singular y plural. Que exista un archivo PO en disco no demuestra que su catálogo compilado esté actualizado. Consulta Gettext para conocer los requisitos del archivo.
Rails #
Rails identifica los archivos YAML cuya raíz es un idioma mediante su clave raíz. Selecciona yaml-root-key y después verifica la configuración de idioma, las funciones auxiliares y la interpolación de Rails. Localiza una aplicación Rails detalla el procedimiento completo, incluidos los archivos por área funcional, el cambio de idioma de las peticiones y las actualizaciones de alcance limitado.
Genera resultados revisables con la traducción recurrente #
Cuando la pantalla funcione, añade los demás catálogos de origen y sus cargadores. Conserva los archivos de destino aceptados junto con la revisión del código de origen y el Lockfile de la CLI. Para los cambios posteriores en el origen, utiliza lingo push --wait para procesar las diferencias habituales; un patrón de archivos como argumento posicional selecciona, en cambio, una planificación de alcance limitado.
Configura los eventos que activan la traducción tras los cambios en el origen y la escritura de los resultados mediante la GitHub App o las recetas de CI. Las recetas de GitLab, Bitbucket y GitHub Actions ejecutan la CLI y necesitan su propio mecanismo para escribir los resultados en el repositorio. Ejecuta la compilación o las comprobaciones de recursos del framework sobre los resultados y después revisa el significado de las traducciones. lingo check no valida todos los frameworks ni garantiza que los archivos PHP, PO o XLIFF estén completos.
Un agente puede ayudar a inspeccionar los cargadores y proponer cambios de configuración. Antes de ampliar el flujo de trabajo, aplica a esos cambios las mismas comprobaciones de selección de archivos de origen, compilación y pantalla renderizada.