Skip to content

7. Internacionalización

7.1. Ejemplo 21: una aplicación bilingüe

Una aplicación bilingüe tiene tres tipos de texto que traducir:

  • el texto de la aplicación: etiquetas y mensajes. Se almacenan en diccionarios, uno por idioma;
  • las fechas y los montos: el paquete [intl] (véase el ejemplo 09), en el idioma actual;
  • el texto del paquete de [Flutter] mismo: los botones de sus ventanas, los días y los meses de su calendario. El paquete [flutter_localizations] los proporciona.

7.1.1. Los diccionarios

{
  "APP": {
    "TITLE": "Exemple 21 - deux langues",
    "LANGUAGE": "Langue"
  },
  "HOME": {
    "HELLO": "Bonjour {{name}} !",
    "TODAY": "Nous sommes le {{date}}.",
    "PRICE": "Une consultation coûte {{price}}.",
    "APPOINTMENTS_zero": "aucun rendez-vous",
    "APPOINTMENTS_one": "un rendez-vous",
    "APPOINTMENTS_other": "{{count}} rendez-vous",
    "ADD": "Ajouter un rendez-vous",
    "REMOVE": "En retirer un",
    "CALENDAR": "Ouvrir le calendrier"
  },
  "ERRORS": {
    "LOGIN_TAKEN": "Ce login est déjà utilisé par un autre compte.",
    "TOO_MANY_ATTEMPTS": "Trop de tentatives infructueuses. Réessayez dans {{minutes}} minute(s)."
  },
  "SERVER": {
    "TITLE": "Traduire une réponse du serveur",
    "EXPLANATION": "Le serveur RdvMedecins ne renvoie que des clés. C'est le client qui les traduit :"
  }
}

Cada texto tiene una clave ("HOME.HELLO"). Los parámetros se escriben como [{{name}}]; un texto en plural tiene varias claves, como [_zero], [_one] y [_other]. Estas son las convenciones de la biblioteca [JavaScript] [i18next] , utilizada por los clientes [React] y [Vue.js] de [RdvMedecins]: el caso de estudio usará sus diccionarios tal cual. El diccionario en inglés tiene las mismas claves:

{
  "APP": {
    "TITLE": "Example 21 - two languages",
    "LANGUAGE": "Language"
  },
  "HOME": {
    "HELLO": "Hello {{name}}!",
    "TODAY": "Today is {{date}}.",
    "PRICE": "A consultation costs {{price}}.",
    "APPOINTMENTS_zero": "no appointment",
    "APPOINTMENTS_one": "one appointment",
    "APPOINTMENTS_other": "{{count}} appointments",
    "ADD": "Add an appointment",
    "REMOVE": "Remove one",
    "CALENDAR": "Open the calendar"
  },
  "ERRORS": {
    "LOGIN_TAKEN": "This login is already used by another account.",
    "TOO_MANY_ATTEMPTS": "Too many failed attempts. Try again in {{minutes}} minute(s)."
  },
  "SERVER": {
    "TITLE": "Translating a server response",
    "EXPLANATION": "The RdvMedecins server only sends keys. The client translates them:"
  }
}

7.1.2. Las traducciones

// =========================================================================
// lib/ex21_i18n/translations.dart - diccionarios, un idioma actual
// -------------------------------------------------------------------------
// Cada idioma tiene su DICCIONARIO, un archivo JSON distribuido con
// la aplicación (assets/i18n/ex21_en.json, ex21_fr.json), donde cada texto
// tiene una CLAVE ("HOME.HELLO"):
//   - t('HOME.HELLO', {'name': 'Marie'}): el texto del idioma
//     ACTUAL, cuyos parámetros {{name}} se reemplazan;
//   - t('HOME.APPOINTMENTS', {'count': n}): un texto en plural;
//     elegimos la clave APPOINTMENTS_zero, _one u _other según n y las reglas
//     del idioma (en francés, 0 y 1 son singular; en inglés,
//     solo 1);
//   - changeLanguage('fr'): carga el otro diccionario y notifica
//     a las pantallas (un ChangeNotifier), que se traducen de nuevo.
// Son las convenciones de la biblioteca JavaScript i18next: los
// diccionarios son los de los clientes Vue.js, Angular y React de
// RdvMedecins... y el servidor, que solo devuelve CLAVES
// ("ERRORS.LOGIN_TAKEN"), también los usa.
// =========================================================================

import 'dart:convert';

import 'package:flutter/services.dart';
import 'package:flutter/widgets.dart';
import 'package:intl/intl.dart';
import 'package:shared_preferences/shared_preferences.dart';

const languages = ['en', 'fr'];

class Translations extends ChangeNotifier {
  final String _prefix; // los diccionarios: assets/i18n/<prefix>_<language>.json
  final SharedPreferences? _storage;
  String _language = 'en';
  Map<String, Object?> _dictionary = {};

  Translations(this._prefix, [this._storage]);

  String get language => _language;

  // el idioma inicial: el guardado en el dispositivo, o si no el del
  // teléfono (si se conoce), o si no inglés
  Future<void> start() async {
    final stored = _storage?.getString('$_prefix.language');
    final device = WidgetsBinding.instance.platformDispatcher.locale.languageCode;
    await changeLanguage(stored ?? (languages.contains(device) ? device : 'en'));
  }

  Future<void> changeLanguage(String language) async {
    // rootBundle: los archivos distribuidos con la aplicación (sección assets del pubspec)
    final json = await rootBundle.loadString('assets/i18n/${_prefix}_$language.json');
    _dictionary = jsonDecode(json) as Map<String, Object?>;
    _language = language;
    await _storage?.setString('$_prefix.language', language);
    notifyListeners();
  }

  // "HOME.HELLO" -> dictionary['HOME']['HELLO']; null si falta
  String? _lookUp(String key) {
    Object? node = _dictionary;
    for (final part in key.split('.')) {
      node = node is Map<String, Object?> ? node[part] : null;
    }
    return node is String ? node : null;
  }

  String t(String key, [Map<String, Object?> params = const {}]) {
    String? text;
    final count = params['count'];
    if (count is int) {
      // Intl.pluralLogic: la forma plural, según las reglas del idioma
      text = Intl.pluralLogic(
        count,
        locale: _language,
        zero: _lookUp('${key}_zero'),
        one: _lookUp('${key}_one'),
        other: _lookUp('${key}_other'),
      );
    }
    text ??= _lookUp(key);
    // una clave desconocida se muestra tal cual: lo que falta se nota de inmediato
    if (text == null) return key;
    // {{name}} -> el valor del parámetro name
    return text.replaceAllMapped(RegExp(r'\{\{(\w+)\}\}'), (m) => '${params[m[1]] ?? m[0]}');
  }
}
  • líneas 30–34: las traducciones: un [ChangeNotifier] (las pantallas se reconstruirán cuando cambie el idioma), que conserva el idioma actual y su diccionario;
  • líneas 42–45: el idioma de origen: el almacenado en el dispositivo; si no, el idioma del teléfono (si se conoce); si no, inglés;
  • líneas 48–54: cambiar de idioma: cargar el diccionario, un archivo JSON incluido con la aplicación ([rootBundle.loadString] lee un archivo de la sección [assets] de [pubspec.yaml]), decodificarlo ([jsonDecode]), guardar la selección y actualizar las pantallas;
  • líneas 58–63: búsqueda de la clave “HOME.HELLO” en el diccionario: recorre, sección por sección, los objetos JSON anidados. [node is Map<String, Object?> ? ... : null]: una verificación de tipo que “promueve” la variable en la rama donde es verdadera;
  • Líneas 66–83: la traducción. Para un plural (un parámetro entero [count]), [Intl.pluralLogic] elige la forma según las reglas del idioma: en francés, 0 y 1 son singular; en inglés, solo 1. Una clave desconocida se muestra tal cual: se ve de inmediato qué falta. Por último, cada [{{name}}] se reemplaza por el valor del parámetro.

¿Por qué no usar la herramienta oficial de [Flutter]? [Flutter] ofrece un generador ([flutter gen-l10n]) que crea, a partir de archivos [.arb], una clase con un método por texto ([AppLocalizations.of(context).hello('Marie')]): las claves se validan en tiempo de compilación. Es la mejor solución para una aplicación en la que todos los textos se conocen de antemano. Pero nuestro servidor devuelve claves (“ERRORS.LOGIN_TAKEN”) que deben traducirse en tiempo de ejecución: un diccionario consultado por clave es mucho más adecuado para este fin y permite compartir los diccionarios con otros clientes.

7.1.3. La página traducida

// =========================================================================
// lib/ex21_i18n/main.dart - una aplicación en dos idiomas
// -------------------------------------------------------------------------
//   - los TEXTOS de la aplicación: los diccionarios (translations.dart),
//     proporcionados a todas las pantallas mediante provider (ver ejemplo 20);
//   - las fechas y los montos: el paquete intl, en el idioma actual
//     (ver ejemplo 09);
//   - los textos del PROPIO Flutter (el calendario, sus botones...): los
//     "delegados" de localización del paquete flutter_localizations, que
//     siguen la propiedad locale de MaterialApp.
// Cambiar el idioma vuelve a traducir toda la pantalla, sin reiniciar.
// =========================================================================

import 'package:flutter/material.dart';
import 'package:flutter_localizations/flutter_localizations.dart';
import 'package:intl/date_symbol_data_local.dart';
import 'package:intl/intl.dart';
import 'package:provider/provider.dart';
import 'package:shared_preferences/shared_preferences.dart';

import 'translations.dart';

// lo que devolvería el servidor de RdvMedecins (ver el capítulo sobre la caja negra)
const serverResponses = [
  (statusCode: 409, key: 'ERRORS.LOGIN_TAKEN', params: <String, String>{}),
  (statusCode: 429, key: 'ERRORS.TOO_MANY_ATTEMPTS', params: {'minutes': '15'}),
];

// context.t('KEY'): un atajo, mediante una extensión de BuildContext
extension Translate on BuildContext {
  String t(String key, [Map<String, Object?> params = const {}]) => watch<Translations>().t(key, params);
}

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await initializeDateFormatting();
  final translations = Translations('ex21', await SharedPreferences.getInstance());
  await translations.start();
  runApp(ChangeNotifierProvider.value(value: translations, child: const Application()));
}

class Application extends StatelessWidget {
  const Application({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      debugShowCheckedModeBanner: false,
      // onGenerateTitle: el título de la aplicación, traducido
      onGenerateTitle: (context) => context.t('APP.TITLE'),
      theme: ThemeData(colorSchemeSeed: Colors.indigo),
      locale: Locale(context.watch<Translations>().language),
      supportedLocales: [for (final l in languages) Locale(l)],
      localizationsDelegates: GlobalMaterialLocalizations.delegates,
      home: const TranslatedPage(),
    );
  }
}

class TranslatedPage extends StatefulWidget {
  const TranslatedPage({super.key});

  @override
  State<TranslatedPage> createState() => _TranslatedPageState();
}

class _TranslatedPageState extends State<TranslatedPage> {
  int _count = 2;
  final _today = DateTime.now();

  @override
  Widget build(BuildContext context) {
    final translations = context.watch<Translations>();
    final language = translations.language;
    // formateadores en el idioma ACTUAL
    final date = DateFormat.yMMMMEEEEd(language).format(_today);
    final price = NumberFormat.currency(locale: language, name: 'EUR', symbol: '€').format(1234.5);

    return Scaffold(
      appBar: AppBar(
        title: Text(context.t('APP.TITLE')),
        actions: [
          // los idiomas: botones "segmentados"
          Padding(
            padding: const EdgeInsets.only(right: 8),
            child: SegmentedButton<String>(
              showSelectedIcon: false,
              segments: [for (final l in languages) ButtonSegment(value: l, label: Text(l.toUpperCase()))],
              selected: {language},
              onSelectionChanged: (choice) => translations.changeLanguage(choice.first),
            ),
          ),
        ],
      ),
      body: ListView(
        padding: const EdgeInsets.all(16),
        children: [
          Card(
            child: Padding(
              padding: const EdgeInsets.all(12),
              child: Column(
                crossAxisAlignment: CrossAxisAlignment.start,
                children: [
                  Text(context.t('HOME.HELLO', {'name': 'Marie'})),
                  Text(context.t('HOME.TODAY', {'date': date})),
                  Text(context.t('HOME.PRICE', {'price': price})),
                  const SizedBox(height: 8),
                  // count: elige la forma plural y reemplaza {{count}}
                  Text(
                    context.t('HOME.APPOINTMENTS', {'count': _count}),
                    style: const TextStyle(fontWeight: FontWeight.bold),
                  ),
                  Wrap(
                    spacing: 8,
                    children: [
                      TextButton(onPressed: () => setState(() => _count++), child: Text(context.t('HOME.ADD'))),
                      TextButton(
                        onPressed: _count == 0 ? null : () => setState(() => _count--),
                        child: Text(context.t('HOME.REMOVE')),
                      ),
                    ],
                  ),
                  // El calendario de Flutter: sus textos siguen el idioma de MaterialApp
                  OutlinedButton.icon(
                    icon: const Icon(Icons.calendar_month),
                    label: Text(context.t('HOME.CALENDAR')),
                    onPressed: () =>
                        showDatePicker(context: context, firstDate: DateTime(2026), lastDate: DateTime(2027, 12, 31)),
                  ),
                ],
              ),
            ),
          ),
          Card(
            child: Padding(
              padding: const EdgeInsets.all(12),
              child: Column(
                crossAxisAlignment: CrossAxisAlignment.start,
                children: [
                  Text(context.t('SERVER.TITLE'), style: Theme.of(context).textTheme.titleSmall),
                  Text(context.t('SERVER.EXPLANATION')),
                  const SizedBox(height: 8),
                  // la clave del servidor ES una clave del diccionario; params proporciona sus parámetros
                  for (final r in serverResponses) ...[
                    Text('${r.statusCode} ${r.key}', style: const TextStyle(fontFamily: 'RobotoMono', fontSize: 12)),
                    Text('→ ${context.t(r.key, r.params)}'),
                    const SizedBox(height: 6),
                  ],
                ],
              ),
            ),
          ),
        ],
      ),
    );
  }
}
  • líneas 30–31: una extensión de [BuildContext] (véase el ejemplo 09): [context.t('KEY')] lee las traducciones proporcionadas más arriba, se suscribe a las actualizaciones y realiza la traducción;
  • líneas 36–38: inicialización: los nombres de los días y de los meses en todos los idiomas, seguidos de las traducciones;
  • línea 39: [ChangeNotifierProvider.value] proporciona un objeto ya creado (por [main]);
  • línea 50: el título de la aplicación, traducido;
  • líneas 52–54: el idioma de [Flutter] sigue al de la aplicación;
  • líneas 76–77: la fecha y el precio, formateados en el idioma actual y luego pasados como parámetros a los textos;
  • líneas 86–90: la selección del idioma en la barra superior;
  • línea 110: [count] selecciona la forma plural y reemplaza a [{{count}}];
  • líneas 124–128: el calendario de [Flutter]: sus textos siguen el idioma de [MaterialApp];
  • líneas 144–146: lo que devolvería el servidor [RdvMedecins]: una clave y sus parámetros. La clave del servidor ES una clave del diccionario.

En inglés (izquierda); en francés, después de una adición (centro); el calendario, en francés (derecha):

Cambiar el idioma vuelve a renderizar toda la pantalla sin reiniciar y sin hacer ninguna solicitud al servidor. El idioma seleccionado se guarda en el dispositivo.