Internacionalizando Aplicações Flutter
Conteúdo
Conceitos Centrais
O Flutter lida com internacionalização (i18n) e localização (l10n) por meio dos pacotes flutter_localizations e intl. A abordagem padrão utiliza arquivos de App Resource Bundle (.arb) para definir strings localizadas, que são então compiladas em uma classe AppLocalizations gerada, proporcionando acesso type-safe dentro da árvore de widgets.
Fluxo de Configuração
Copie e acompanhe esta checklist ao inicializar a internacionalização em um projeto Flutter:
- Progresso da Tarefa
- 1. Adicionar dependências ao
pubspec.yaml. - 2. Ativar a flag
generate. - 3. Criar o arquivo de configuração
l10n.yaml. - 4. Configurar o
MaterialAppouCupertinoApp.
- 1. Adicionar dependências ao
1. Adicionar Dependências
Adicione os pacotes de localização necessários ao projeto. Execute os seguintes comandos no terminal:
flutter pub add flutter_localizations --sdk=flutter
flutter pub add intl:any
Verifique se seu pubspec.yaml inclui o seguinte sob dependencies:
dependencies:
flutter:
sdk: flutter
flutter_localizations:
sdk: flutter
intl: any
2. Ativar Geração de Código
Abra o pubspec.yaml e ative a flag generate na seção flutter para automatizar tarefas de localização:
flutter:
generate: true
3. Criar Arquivo de Configuração
Crie um novo arquivo chamado l10n.yaml no diretório raiz do projeto Flutter. Defina o diretório de entrada, o arquivo template e o arquivo de saída:
arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart
synthetic-package: true
4. Configurar o Ponto de Entrada da Aplicação
Importe as localizações geradas e a biblioteca flutter_localizations no seu main.dart. Injete os delegates e os locales suportados no seu MaterialApp ou CupertinoApp.
import 'package:flutter_localizations/flutter_localizations.dart';
import 'package:flutter_gen/gen_l10n/app_localizations.dart'; // Ajuste o caminho se synthetic-package for false
// ... dentro do método build
return MaterialApp(
localizationsDelegates: const [
AppLocalizations.delegate,
GlobalMaterialLocalizations.delegate,
GlobalWidgetsLocalizations.delegate,
GlobalCupertinoLocalizations.delegate,
],
supportedLocales: const [
Locale('en'), // Inglês
Locale('es'), // Espanhol
],
home: const MyHomePage(),
);
Fluxo de Implementação
Siga este fluxo ao adicionar ou modificar conteúdo localizado.
1. Definir Arquivos ARB
- Se estiver criando NOVO conteúdo: Adicione a string base ao arquivo template (
lib/l10n/app_en.arb). Inclua uma descrição para contexto. - Se estiver EDITANDO conteúdo existente: Localize a chave em todos os arquivos
.arbsuportados e atualize os valores.
{
"helloWorld": "Olá Mundo!",
"@helloWorld": {
"description": "A saudação convencional do programador novato"
}
}
Crie arquivos correspondentes para outros locales (ex.: app_es.arb):
{
"helloWorld": "¡Hola Mundo!"
}
2. Gerar Classes de Localização
Execute o seguinte comando para acionar a geração de código:
flutter pub get
Loop de Feedback: Execute o validador -> revise a saída do terminal em busca de erros de sintaxe ARB -> corrija vírgulas ausentes ou placeholders incompatíveis -> execute novamente flutter pub get.
3. Consumir Strings Localizadas
Acesse as strings localizadas na sua árvore de widgets usando AppLocalizations.of(context). Certifique-se de que o widget que faz essa chamada seja um descendente do MaterialApp.
Text(AppLocalizations.of(context)!.helloWorld)
Formatação Avançada
Use placeholders para dados dinâmicos, plurais e seletores condicionais.
Placeholders
Defina parâmetros entre chaves e especifique seu tipo no objeto de metadados.
"hello": "Olá {userName}",
"@hello": {
"description": "Uma mensagem com um único parâmetro",
"placeholders": {
"userName": {
"type": "String",
"example": "João"
}
}
}
Plurais
Use a sintaxe plural para lidar com variações de strings baseadas em quantidade. O caso other é obrigatório.
"nWombats": "{count, plural, =0{nenhum vombate} =1{1 vombate} other{{count} vombates}}",
"@nWombats": {
"description": "Uma mensagem plural",
"placeholders": {
"count": {
"type": "num",
"format": "compact"
}
}
}
Seletores
Use a sintaxe select para strings condicionais, como texto com gênero.
"pronoun": "{gender, select, male{ele} female{ela} other{elu}}",
"@pronoun": {
"description": "Uma mensagem com gênero",
"placeholders": {
"gender": {
"type": "String"
}
}
}
Exemplos
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
Implementação Completa de 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)),
],
);
}
}