Localiza una aplicación de Flutter

Traduce mensajes ARB, genera recursos de Flutter y comprueba la pantalla resultante en cada idioma de destino.

Las herramientas de localización de Flutter convierten los mensajes ARB en métodos que tus widgets invocan. Lingo.dev traduce esos recursos ARB para que puedas añadir idiomas sin cambiar la API generada. Empieza por una pantalla con un saludo y un recuento de elementos que te permitan comprobar a la vez el texto, las variables y el funcionamiento de los plurales.

Este procedimiento parte de que el proyecto ya carga el archivo ARB de origen mediante la generación de recursos de localización de Flutter. Conserva l10n.yaml, el generador y las llamadas existentes de los widgets. En este caso, Lingo.dev se encarga de traducir los archivos; Flutter sigue seleccionando el idioma y mostrando los mensajes.

Dale a cada mensaje la información que necesita #

Si el archivo de origen está en lib/l10n/app_en.arb, utiliza un catálogo como este:

json
{
  "@@locale": "en",
  "welcome": "Welcome, {name}",
  "@welcome": {
    "description": "Greeting on the signed-in account screen",
    "placeholders": { "name": { "type": "String" } }
  },
  "itemCount": "{count, plural, =0{No items} =1{One item} other{{count} items}}",
  "@itemCount": {
    "description": "Number of items in the cart",
    "placeholders": { "count": { "type": "int" } }
  }
}

La descripción explica a quien traduce para qué se utiliza el mensaje. Las definiciones de los marcadores de posición indican a Flutter qué valores proporciona el código que realiza la llamada. El controlador de ARB traduce las dos cadenas de los mensajes, conserva los metadatos y actualiza el campo @@locale existente con el idioma de destino.

Ejecuta primero el generador de localización del proyecto sobre el archivo de origen y utiliza en la pantalla los métodos generados para el saludo y el recuento. Así comprobarás que el catálogo original y el código que lo invoca encajan antes de añadir otro idioma.

Instala la versión actual de la CLI y autentícate desde la raíz del proyecto:

sh
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets de,fr --files 'lib/l10n/app_en.arb' --yes
lingo link

init escribe .lingo/config.json; link selecciona la organización y el motor de localización. Conserva los identificadores generados. Los campos de localización deben seleccionar solo el archivo de origen:

json
{
  "sourceLocale": "en",
  "targetLocales": ["de", "fr"],
  "files": [
    { "pattern": "lib/l10n/app_en.arb", "format": "flutter" }
  ]
}

Esta es la sección de localización de la configuración vinculada; no sustituye a los identificadores de la organización y del motor de localización. La extensión .arb también selecciona flutter automáticamente. Esta estructura genera app_de.arb y app_fr.arb; comprueba que el generador del proyecto los lee. Si utilizas otra estructura, establece una ruta de destino explícita.

Evita patrones de origen como app_*.arb que también seleccionen catálogos traducidos. Para las variantes regionales de los idiomas, adapta la forma de escribir el nombre del archivo a la configuración del proyecto de Flutter, en lugar de dar por hecho que cualquier cadena de idioma se puede usar sin cambios en un nombre de archivo.

Traduce y genera los recursos de destino #

Para los archivos de destino que falten, ejecuta:

sh
lingo push --backfill-missing --wait

El comando espera a que termine la ejecución y recupera los archivos. Si la ejecución queda pendiente de revisión o falla, resuelve la situación antes de generar los recursos de la versión que vas a publicar. Un primer envío simple puede establecer la referencia inicial del origen sin solicitar las traducciones que faltan.

Revisa las claves de destino, las descripciones, los nombres y tipos de los marcadores de posición y @@locale. Después, ejecuta la generación de recursos de localización de Flutter, el análisis, las pruebas y la compilación del proyecto. Corrige cualquier expresión ICU no válida, marcador de posición que falte o tipo incompatible antes de continuar. La reconstrucción de ARB conserva los metadatos, pero no valida cada mensaje traducido con el generador de Flutter.

Abre la pantalla en alemán y en francés. Introduce un nombre corto y otro largo y, después, prueba con recuentos de 0, 1, 2 y un número mayor. Lee cómo están redactados los plurales, en lugar de comprobar solo que aparece un número. Algunos idiomas pueden necesitar categorías que no están presentes en el origen en inglés, así que revisa las formas necesarias en cada idioma de destino. Comprueba la selección del idioma, el idioma alternativo, el aumento de longitud del texto y la dirección de escritura cuando corresponda. El formato de fechas y números sigue dependiendo de Flutter en tiempo de ejecución.

Mantén las actualizaciones posteriores vinculadas al origen #

Mantén juntos la configuración, el origen, los destinos aceptados y .lingo/lock.json. Después de cambiar un mensaje de origen, ejecuta lingo push --wait y revisa ese mensaje junto a otro cercano que no haya cambiado. Cambiar solo la descripción no convierte por sí mismo el texto del mensaje en una nueva tarea de traducción; utiliza una actualización acotada cuando el contexto revisado deba dar lugar a una nueva traducción.

No edites los archivos de destino mientras esté pendiente la escritura de los resultados. Para proteger las correcciones locales de los archivos de destino, realiza el envío sin --wait, revisa lingo pull --dry-run y recupera después los resultados con lingo pull en el checkout desde el que hiciste el envío. Los demás equipos necesitan las traducciones guardadas en un commit o una transferencia explícita de los artefactos; no des por hecho que comparten la última ejecución. Consulta Conservar las traducciones revisadas para obtener más información sobre la recuperación.

Cuando este ciclo funcione, utiliza la GitHub App o la automatización de CI para repetir la traducción y la generación de recursos antes de la revisión. Los archivos XML de Android y los recursos de Apple nativos tienen requisitos distintos en cuanto a los archivos y al funcionamiento en tiempo de ejecución; mantenlos separados de la generación de ARB en un proyecto multiplataforma.