Internacionalizando Aplicaciones Flutter
Contenido
Conceptos Básicos
Flutter maneja la internacionalización (i18n) y la localización (l10n) a través de los paquetes flutter_localizations e intl. El enfoque estándar utiliza archivos App Resource Bundle (.arb) para definir cadenas localizadas, que luego se compilan en una clase generada AppLocalizations para un acceso seguro de tipos dentro del árbol de widgets.
Flujo de Configuración
Copia y sigue esta lista de verificación al inicializar la internacionalización en un proyecto Flutter:
- Progreso de la Tarea
- 1. Agregar dependencias a
pubspec.yaml. - 2. Habilitar la bandera
generate. - 3. Crear el archivo de configuración
l10n.yaml. - 4. Configurar
MaterialAppoCupertinoApp.
- 1. Agregar dependencias a
1. Agregar Dependencias
Agrega los paquetes de localización requeridos al proyecto. Ejecuta los siguientes comandos en la terminal:
flutter pub add flutter_localizations --sdk=flutter
flutter pub add intl:any
Verifica que tu pubspec.yaml incluya lo siguiente bajo dependencies:
dependencies:
flutter:
sdk: flutter
flutter_localizations:
sdk: flutter
intl: any
2. Habilitar Generación de Código
Abre pubspec.yaml y habilita la bandera generate dentro de la sección flutter para automatizar las tareas de localización:
flutter:
generate: true
3. Crear Archivo de Configuración
Crea un nuevo archivo llamado l10n.yaml en el directorio raíz del proyecto Flutter. Define el directorio de entrada, el archivo de plantilla y el archivo de salida:
arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart
synthetic-package: true
4. Configurar el Punto de Entrada de la Aplicación
Importa las localizaciones generadas y la librería flutter_localizations en tu main.dart. Inyecta los delegados y los locales soportados en tu MaterialApp o CupertinoApp.
import 'package:flutter_localizations/flutter_localizations.dart';
import 'package:flutter_gen/gen_l10n/app_localizations.dart'; // Ajusta la ruta si synthetic-package es false
// ... dentro del método build
return MaterialApp(
localizationsDelegates: const [
AppLocalizations.delegate,
GlobalMaterialLocalizations.delegate,
GlobalWidgetsLocalizations.delegate,
GlobalCupertinoLocalizations.delegate,
],
supportedLocales: const [
Locale('en'), // Inglés
Locale('es'), // Español
],
home: const MyHomePage(),
);
Flujo de Implementación
Sigue este flujo de trabajo al agregar o modificar contenido localizado.
1. Definir Archivos ARB
- Si creas contenido NUEVO: Agrega la cadena base al archivo de plantilla (
lib/l10n/app_en.arb). Incluye una descripción para contexto. - Si EDITAS contenido existente: Localiza la clave en todos los archivos
.arbsoportados y actualiza los valores.
{
"helloWorld": "Hello World!",
"@helloWorld": {
"description": "El saludo convencional del programador novato"
}
}
Crea archivos correspondientes para otros idiomas (ej., app_es.arb):
{
"helloWorld": "¡Hola Mundo!"
}
2. Generar Clases de Localización
Ejecuta el siguiente comando para activar la generación de código:
flutter pub get
Bucle de retroalimentación: Ejecuta el validador -> revisa la salida del terminal en busca de errores de sintaxis ARB -> corrige comas faltantes o placeholders no coincidentes -> vuelve a ejecutar flutter pub get.
3. Consumir Cadenas Localizadas
Accede a las cadenas localizadas en tu árbol de widgets usando AppLocalizations.of(context). Asegúrate de que el widget que lo llama sea descendiente de MaterialApp.
Text(AppLocalizations.of(context)!.helloWorld)
Formato Avanzado
Usa placeholders para datos dinámicos, plurales y selecciones condicionales.
Placeholders
Define parámetros entre llaves y especifica su tipo en el objeto de metadatos.
"hello": "Hello {userName}",
"@hello": {
"description": "Un mensaje con un solo parámetro",
"placeholders": {
"userName": {
"type": "String",
"example": "Bob"
}
}
}
Plurales
Usa la sintaxis plural para manejar variaciones de cadenas según la cantidad. El caso other es obligatorio.
"nWombats": "{count, plural, =0{no hay wombats} =1{1 wombat} other{{count} wombats}}",
"@nWombats": {
"description": "Un mensaje plural",
"placeholders": {
"count": {
"type": "num",
"format": "compact"
}
}
}
Selectores
Usa la sintaxis select para cadenas condicionales, como texto con género.
"pronoun": "{gender, select, male{él} female{ella} other{elle}}",
"@pronoun": {
"description": "Un mensaje con género",
"placeholders": {
"gender": {
"type": "String"
}
}
}
Ejemplos
l10n.yaml Completo
arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart
synthetic-package: true
use-escaping: true
Implementación Completa de un Widget
import 'package:flutter/material.dart';
import 'package:flutter_gen/gen_l10n/app_localizations.dart';
class GreetingWidget extends StatelessWidget {
final String userName;
final int notificationCount;
const GreetingWidget({
super.key,
required this.userName,
required this.notificationCount,
});
@override
Widget build(BuildContext context) {
final l10n = AppLocalizations.of(context)!;
return Column(
children: [
Text(l10n.hello(userName)),
Text(l10n.nWombats(notificationCount)),
],
);
}
}