Skip to content

7. Internacionalização

7.1. Exemplo 21: um aplicativo bilíngue

Um aplicativo bilíngue tem três tipos de texto a traduzir:

  • os textos do aplicativo: rótulos e mensagens. Eles são guardados em dicionários, um por idioma;
  • as datas e os valores: o pacote [intl] (veja o exemplo 09), no idioma atual;
  • os textos do pacote [Flutter] em si: os botões de suas janelas, os dias e os meses de seu calendário. O pacote [flutter_localizations] fornece esses textos.

7.1.1. Os dicionários

{
  "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 tem uma chave ("HOME.HELLO"). Os parâmetros são escritos como [{{name}}]; um texto no plural tem várias chaves, como [_zero], [_one] e [_other]. Essas são as convenções da biblioteca [JavaScript] [i18next] , usada pelos clientes [React] e [Vue.js] do [RdvMedecins]: o estudo de caso usará seus dicionários como estão. O dicionário em inglês tem as mesmas chaves:

{
  "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. As traduções

// =========================================================================
// lib/ex21_i18n/translations.dart - dicionários, um idioma atual
// -------------------------------------------------------------------------
// Cada idioma tem seu DICIONÁRIO, um arquivo JSON distribuído com
// o aplicativo (assets/i18n/ex21_en.json, ex21_fr.json), onde cada texto
// tem uma CHAVE ("HOME.HELLO"):
//   - t('HOME.HELLO', {'name': 'Marie'}): o texto do idioma
//     ATUAL, cujos parâmetros {{name}} são substituídos;
//   - t('HOME.APPOINTMENTS', {'count': n}): um texto no plural;
//     escolhemos a chave APPOINTMENTS_zero, _one ou _other de acordo com n e as regras
//     do idioma (em francês, 0 e 1 são singular; em inglês,
//     somente 1);
//   - changeLanguage('fr'): carrega o outro dicionário e notifica as
//     telas (um ChangeNotifier), que se traduzem de novo.
// Estas são as convenções da biblioteca JavaScript i18next: os
// dicionários são os dos clientes Vue.js, Angular e React do
// RdvMedecins... e o servidor, que só retorna CHAVES
// ("ERRORS.LOGIN_TAKEN"), também os 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; // os dicionários: assets/i18n/<prefix>_<language>.json
  final SharedPreferences? _storage;
  String _language = 'en';
  Map<String, Object?> _dictionary = {};

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

  String get language => _language;

  // o idioma inicial: o guardado no dispositivo, senão o do
  // celular (se for conhecido), senão o 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: os arquivos distribuídos com o aplicativo (seção assets do 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 se ausente
  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: a forma plural, de acordo com as regras do idioma
      text = Intl.pluralLogic(
        count,
        locale: _language,
        zero: _lookUp('${key}_zero'),
        one: _lookUp('${key}_one'),
        other: _lookUp('${key}_other'),
      );
    }
    text ??= _lookUp(key);
    // uma chave desconhecida é exibida como está: o que falta é visto na hora
    if (text == null) return key;
    // {{name}} -> o valor do parâmetro name
    return text.replaceAllMapped(RegExp(r'\{\{(\w+)\}\}'), (m) => '${params[m[1]] ?? m[0]}');
  }
}
  • linhas 30–34: as traduções: um [ChangeNotifier] (as telas serão reconstruídas quando o idioma mudar), que guarda o idioma atual e seu dicionário;
  • linhas 42–45: o idioma inicial: o armazenado no dispositivo; caso contrário, o idioma do celular (se conhecido); caso contrário, o inglês;
  • linhas 48–54: mudar o idioma: carregar o dicionário, um arquivo JSON incluído no aplicativo ([rootBundle.loadString] lê um arquivo da seção [assets] do [pubspec.yaml]), decodificá-lo ([jsonDecode]), salvar a seleção e atualizar as telas;
  • linhas 58–63: busca a chave “HOME.HELLO” no dicionário: percorre, seção por seção, os objetos JSON aninhados. [node is Map<String, Object?> ? ... : null]: uma verificação de tipo, que “promove” a variável no ramo em que é verdadeira;
  • Linhas 66–83: a tradução. Para um plural (um parâmetro inteiro [count]), [Intl.pluralLogic] escolhe a forma de acordo com as regras do idioma: em francês, 0 e 1 são singular; em inglês, apenas 1. Uma chave desconhecida é exibida como está: dá para ver imediatamente o que está faltando. Por fim, cada [{{name}}] é substituído pelo valor do parâmetro.

Por que não usar a ferramenta oficial do [Flutter]? [Flutter] oferece um gerador ([flutter gen-l10n]) que cria, a partir de arquivos [.arb], uma classe com um método por texto ([AppLocalizations.of(context).hello('Marie')]): as chaves são validadas em tempo de compilação. É a melhor solução para uma aplicação em que todos os textos são conhecidos de antemão. Mas nosso servidor devolve chaves (“ERRORS.LOGIN_TAKEN”) que precisam ser traduzidas em tempo de execução: um dicionário, consultado pela chave, é muito mais adequado para isso e permite compartilhar os dicionários com outros clientes.

7.1.3. A página traduzida

// =========================================================================
// lib/ex21_i18n/main.dart - um aplicativo em dois idiomas
// -------------------------------------------------------------------------
//   - os TEXTOS do aplicativo: os dicionários (translations.dart),
//     fornecidos a todas as telas pelo provider (veja o exemplo 20);
//   - as datas e os valores monetários: o pacote intl, no idioma atual
//     (veja o exemplo 09);
//   - os textos do PRÓPRIO Flutter (o calendário, seus botões...): os
//     "delegates" de localização do pacote flutter_localizations, que
//     acompanham a propriedade locale de MaterialApp.
// Mudar o idioma traduz toda a tela de novo, sem 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';

// o que o servidor RdvMedecins retornaria (veja o capítulo sobre a caixa-preta)
const serverResponses = [
  (statusCode: 409, key: 'ERRORS.LOGIN_TAKEN', params: <String, String>{}),
  (statusCode: 429, key: 'ERRORS.TOO_MANY_ATTEMPTS', params: {'minutes': '15'}),
];

// context.t('KEY'): um atalho, por meio de uma extension 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: o título do aplicativo, traduzido
      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;
    // formatadores no idioma ATUAL
    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: [
          // os idiomas: botões "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: escolhe a forma plural e substitui {{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')),
                      ),
                    ],
                  ),
                  // O calendário do Flutter: seus textos acompanham o 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),
                  // a chave do servidor É uma chave do dicionário; params fornece seus 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),
                  ],
                ],
              ),
            ),
          ),
        ],
      ),
    );
  }
}
  • linhas 30–31: uma extensão de [BuildContext] (veja o exemplo 09): [context.t('KEY')] lê as traduções fornecidas acima, assina as atualizações e realiza a tradução;
  • linhas 36–38: inicialização: os nomes dos dias e dos meses em todos os idiomas, seguidos das traduções;
  • linha 39: [ChangeNotifierProvider.value] fornece um objeto JÁ criado (por [main]);
  • linha 50: o título da aplicação, traduzido;
  • linhas 52–54: o idioma do [Flutter] em si segue o da aplicação;
  • linhas 76–77: a data e o preço, formatados no idioma atual e depois passados como parâmetros aos textos;
  • linhas 86–90: a seleção do idioma na barra superior;
  • linha 110: [count] seleciona a forma plural e substitui [{{count}}];
  • linhas 124–128: o calendário do [Flutter]: seus textos seguem o idioma do [MaterialApp];
  • linhas 144–146: o que o servidor [RdvMedecins] devolveria: uma chave e seus parâmetros. A chave do servidor É uma chave do dicionário.

Em inglês (à esquerda); em francês, após uma inclusão (no meio); o calendário, em francês (à direita):

A troca de idioma renderiza novamente a tela inteira, sem reiniciar e sem fazer nenhuma requisição ao servidor. O idioma selecionado é armazenado no dispositivo.