Localiza una aplicación web
Conecta los catálogos traducidos con la selección de idioma, la carga de recursos y las verificaciones de renderizado de tu framework.
Si tu aplicación web ya renderiza mensajes desde archivos de idioma, conserva la configuración que ya funciona. Lingo.dev puede traducir los catálogos de origen mientras la biblioteca existente sigue seleccionando el idioma, cargando los mensajes y renderizándolos. Completa ese ciclo en una pantalla antes de traducir el resto de la aplicación.
Esta guía abarca catálogos existentes basados en claves para distintos frameworks. Para mensajes basados en texto de origen y contexto con @lingo.dev/react, usa la guía de inicio rápido de React o la guía de migración. Los identificadores que se extraen difieren 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 con una etiqueta, un mensaje con variables y un mensaje plural o condicional. Renderízala en el idioma de origen con la biblioteca existente. Conserva sus espacios de nombres, la sintaxis de interpolación y las claves de búsqueda; una traducción genérica de JSON no convierte la gramática de mensajes de una biblioteca en la de otra.
Para un archivo de origen existente 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 .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 ID reales de la organización y del motor de localización generados durante la vinculación. Si usas otro framework, reemplaza la ruta de origen por la que aparece en las secciones siguientes. Selecciona solo los catálogos de origen y asegúrate de que la ruta de destino coincida con la del cargador. Usa rutas de destino explícitas para estructuras sin un segmento de idioma.
Traduce los destinos faltantes con:
lingo push --backfill-missing --waitAl terminar, 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 se describe a continuación conecta ese archivo con la solicitud o la compilación real. Un primer envío simple puede guardar una versión de referencia sin solicitar las traducciones faltantes.
Mantén los destinos sin cambios mientras esperas a que se ejecute la escritura de resultados. Si necesitas proteger las correcciones locales existentes contra conflictos, envía sin --wait, inspecciona lingo pull --dry-run y luego recupera 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 búsqueda que ya usas. Un archivo de origen en public/locales/en/translation.json corresponde a public/locales/es/translation.json. Si la aplicación usa varios espacios de nombres, configura cada archivo de origen en inglés en lugar de usar un patrón de archivos que también incluya los archivos generados en español.
Haz que el cargador de recursos de i18next solicite el idioma y el espacio de nombres de destino. Luego usa las llamadas useTranslation existentes para renderizar el caso de prueba. Verifica la sustitución de variables y la convención de claves de plural que usa tu versión instalada de i18next. 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 solicitud de red del recurso como el texto visible; usar el inglés como idioma de respaldo puede ocultar la falta de un archivo en español.
App Router de Next.js con next-intl #
Para next-intl, un archivo de origen habitual es messages/en.json, que genera messages/es.json. Configura la resolución del idioma al procesar cada solicitud y carga los mensajes correspondientes en tu configuración de next-intl. Mantén las rutas y la navegación por idioma en sintonía con esa elección.
Renderiza el caso de prueba tanto con una solicitud directa en el idioma de destino como al navegar desde otro idioma. Verifica 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 por sí solo no agrega un segmento de idioma de App Router ni un selector de idioma. Para documentos extensos que acompañen estos catálogos de interfaz, usa Markdoc con Next.js.
Pages Router de Next.js con next-i18next #
Con next-i18next, configura el patrón de origen para que coincida con el directorio de idiomas y los espacios de nombres que ya usas. Si son public/locales/en/common.json y public/locales/en/checkout.json, traduce ambos a sus archivos equivalentes en español. Si usas messages/en.json, conserva el cargador personalizado que realmente lo consume.
Carga los espacios de nombres necesarios mediante el mecanismo de carga de datos que ya usa la página, ya sea del lado del servidor o estático. Verifica una solicitud directa de la página localizada y un cambio de ruta del lado del 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 existente de i18n. Establece el idioma seleccionado donde tu aplicación ya lo administra.
Prueba las llamadas $t o useI18n en el caso de prueba. Verifica las claves anidadas, la interpolación y la sintaxis de mensajes plurales de la biblioteca instalada. Prueba tanto un cambio de idioma sin recargar como una carga de página desde cero. Si los diccionarios se empaquetan mediante importaciones, confirma que el archivo traducido esté incluido en la compilación.
Nuxt con el módulo i18n #
Para 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 tu versión 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. Agregar un destino a la configuración de traducción no lo agrega automáticamente a la lista de idiomas de Nuxt.
Diccionarios de Svelte y SvelteKit #
Para 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 usa la aplicación. Si la aplicación usa SSR, prueba una nueva solicitud renderizada en el servidor y luego un cambio de idioma en el cliente. Verifica que el estado del idioma se mantenga aislado entre las solicitudes al servidor y que el diccionario de destino termine de cargarse. No uses el resultado del idioma de respaldo como prueba de que la traducción está completa.
XLIFF de Angular #
Primero usa el flujo de trabajo de i18n de Angular para marcar y extraer los mensajes. El procesador de XLIFF admite XLIFF 1.2 y 2.x, incluidos texto sin formato y códigos en línea. El texto dentro de códigos emparejados como <g> y <pc> se traduce sin alterar su estructura; los códigos independientes como <ph> permanecen protegidos. Mantén estables los identificadores de mensajes y 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 corresponde a src/locale/es/messages.xlf. XLIFF no usa la sustitución de sufijos de messages.en.xlf a messages.es.xlf; usa el directorio de idiomas 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 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 compila un paquete localizado faltante. Verifica la cobertura de mensajes y el renderizado de los marcadores de posición antes de aceptar el paquete.
Astro #
Para las etiquetas de interfaz, traduce src/i18n/en.json a su archivo equivalente de destino y haz que tu propio cargador de diccionarios lo seleccione. Para las colecciones de contenido, traduce los archivos de origen Markdown o MDX específicos de cada idioma y usa el flujo de trabajo de contenido estático.
Configura las rutas por idioma de Astro de forma independiente de la traducción. Compila y visita las rutas de destino generadas. Verifica los enlaces entre las versiones de cada idioma 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 separadas.
Laravel #
Para la localización de Laravel, un archivo de origen PHP como lang/en/messages.php corresponde a lang/es/messages.php. Conserva las claves de los arreglos y los nombres de sustitución en tiempo de ejecución. Consulta la referencia del formato PHP antes de seleccionar archivos con código ejecutable que vaya más allá de la estructura de catálogo admitida.
Establece el idioma de la solicitud mediante el middleware existente o la política del controlador de la aplicación 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 solicitud en cada idioma admitido y un caso con idioma de respaldo; los archivos traducidos no seleccionan el idioma de la solicitud.
Django #
Usa el flujo de trabajo de extracción de Django para crear locale/en/LC_MESSAGES/django.po y luego traduce ese archivo PO de origen al directorio del idioma de destino. Conserva los identificadores de mensajes de gettext, el contexto y la interpolación. Compila el PO traducido para generar el recurso que Django realmente carga mediante el paso de compilación de gettext que ya usa el proyecto.
Configura la selección de idioma de Django y la lista de idiomas. Verifica una solicitud localizada a través del middleware de traducción y renderiza las llamadas en singular y plural. Que un archivo PO exista en disco no demuestra que su catálogo compilado esté actualizado. Consulta Gettext para conocer los requisitos del archivo.
Rails #
Rails reconoce los archivos YAML cuya raíz es un idioma por su clave raíz. Selecciona yaml-root-key y luego verifica la configuración de idiomas, las funciones auxiliares y la interpolación de Rails. Localiza una aplicación de Rails detalla el procedimiento completo, incluidos los archivos separados por función, el cambio de idioma de las solicitudes y las actualizaciones de alcance limitado.
Haz que las traducciones recurrentes generen resultados fáciles de revisar #
Una vez que la pantalla funcione, agrega los catálogos de origen restantes y sus cargadores. Conserva los destinos aceptados junto con la revisión del origen y el Lockfile de la CLI. Los cambios posteriores en el origen usan lingo push --wait para procesar las diferencias habituales; en cambio, un patrón de archivos como argumento posicional selecciona una planificación de alcance limitado.
Elige los activadores por cambios en el origen y el mecanismo de escritura de 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 las verificaciones de compilación o de recursos del framework sobre los resultados y luego 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. Aplica a esas modificaciones las mismas verificaciones de selección de archivos de origen, compilación y pantallas renderizadas antes de ampliar el flujo de trabajo.