Flutter ARB

Traducción con IA para archivos ARB de Flutter con Lingo.dev CLI

¿Qué es Flutter ARB?

Flutter ARB (Application Resource Bundle) es un formato basado en JSON utilizado por el framework Flutter de Google para gestionar cadenas de texto localizadas. Admite metadatos, marcadores de posición y formato de mensajes ICU para crear aplicaciones compiladas de forma nativa.

¿Qué es Lingo.dev CLI?

Lingo.dev CLI es una herramienta 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 flujos de trabajo existentes.

Para saber más, consulta Descripción general.

Acerca de esta guía

Esta guía explica cómo traducir archivos ARB de Flutter con Lingo.dev CLI.

Aprenderás a:

  • Crear un proyecto desde cero
  • Configurar un flujo de trabajo de traducción
  • Generar traducciones con IA

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 flujo de trabajo de traducción, incluyendo entre 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 el idioma de origen

El idioma de origen es el idioma y región original en el que se escribió tu contenido. Para configurar el idioma 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": {}
}

El idioma de origen debe proporcionarse como una etiqueta de idioma BCP 47.

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

Paso 3. Configurar los idiomas de destino

Los idiomas de destino son los idiomas y regiones a los que deseas traducir tu contenido. Para configurar los idiomas 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 uno o más archivos ARB que contengan el contenido a traducir. Estos archivos deben estar ubicados en una ruta que incluya el idioma de origen en alguna parte de la ruta (por ejemplo, como un nombre de directorio como en/ o como parte del nombre de archivo como messages.en.arb).

Para los archivos ARB de Flutter, se aplican los siguientes requisitos:

  • Cada clave de mensaje debe tener un valor de traducción correspondiente
  • Las entradas de metadatos (que comienzan con @) se conservan pero no se traducen
  • El campo de metadatos @@locale identifica el idioma
  • Los marcadores de posición ({name}) se conservan durante la traducción
  • Se admite el formato de mensaje ICU para plurales y selectores

Por ejemplo:

{
  "@@locale": "en",
  "welcome_message": "Welcome to our Flutter app",
  "@welcome_message": {
    "description": "The main welcome message shown on the home screen"
  },
  "login_button": "Log In",
  "greeting_with_name": "Hello {name}!",
  "@greeting_with_name": {
    "placeholders": {
      "name": {
        "type": "String"
      }
    }
  }
}

Paso 5. Crear un bucket

  1. En el archivo i18n.json, añade un objeto "flutter" al objeto buckets:

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

  2. En el objeto "flutter", 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": {
    "flutter": {
      "include": ["./[locale]/example.arb"]
    }
  }
}

    Estos patrones definen qué archivos traducir.

    Los patrones en sí:

    • deben contener [locale] como marcador de posición para el idioma configurado
    • pueden apuntar a rutas de archivo (por ejemplo, "[locale]/config.arb")
    • pueden usar asteriscos como marcadores de posición comodín (por ejemplo, "[locale]/*.arb")

    Los patrones glob recursivos (por ejemplo, **/*.arb) no son compatibles.

Paso 6. Configurar un LLM

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

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

  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.
  4. Utiliza el LLM configurado para traducir el contenido extraído.
  5. Escribe el contenido traducido de vuelta al sistema de archivos.

La primera vez que se generan 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.arb

{
  "@@locale": "en",
  "welcome_message": "Welcome to our Flutter app",
  "@welcome_message": {
    "description": "The main welcome message shown on the home screen",
    "context": "greeting"
  },
  "login_button": "Log In",
  "signup_button": "Sign Up",
  "greeting_with_name": "Hello {name}!",
  "@greeting_with_name": {
    "description": "Greeting message with user's name",
    "placeholders": {
      "name": {
        "type": "String",
        "description": "The user's display name"
      }
    }
  },
  "item_count": "{count, plural, =0 {No items} one {# item} other {# items}}",
  "@item_count": {
    "description": "Message showing the number of items with proper pluralization",
    "placeholders": {
      "count": {
        "type": "int",
        "description": "The number of items"
      }
    }
  }
}

es/example.arb

{
  "@@locale": "es",
  "welcome_message": "Bienvenido a nuestra aplicación Flutter",
  "@welcome_message": {
    "description": "The main welcome message shown on the home screen",
    "context": "greeting"
  },
  "login_button": "Iniciar sesión",
  "signup_button": "Registrarse",
  "greeting_with_name": "¡Hola {name}!",
  "@greeting_with_name": {
    "description": "Greeting message with user's name",
    "placeholders": {
      "name": {
        "type": "String",
        "description": "The user's display name"
      }
    }
  },
  "item_count": "{count, plural, =0 {Sin elementos} one {# elemento} other {# elementos}}",
  "@item_count": {
    "description": "Message showing the number of items with proper pluralization",
    "placeholders": {
      "count": {
        "type": "int",
        "description": "The number of items"
      }
    }
  }
}

i18n.json

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

i18n.lock

version: 1
checksums:
  88559ecadc7cff52625bd3a47e51dd78:
    welcome_message: 9c56d00796c3c7facba6a25275de5b7b
    login_button: 0029e5a35676c0051e761fcd046ef9ee
    signup_button: 0dd2ae69be4618c1f9e615774a4509ca
    error_network: e0becd5fc88e85a97c6987b96c80fb11
    success_message: e6dcd73052dc41dbe05d86af9887d2c4
    user_profile_title: bee775ff7216747b2111e93cefa57ddc
    settings_screen_title: 8df6777277469c1fd88cc18dde2f1cc3
    cancel_action: 2e2a849c2223911717de8caa2c71bade
    confirm_action: 90930b51154032f119fa75c1bd422d8b
    greeting_with_name: 218521f06746e82ba44d68c8a5bb210c
    item_count: d8d083b56bc155cf0997ea6ae989b83f
    user_status: 903b5a6edde5368dd9089accdc1b1f9d