Localização no Flutter: arquivos ARB, intl e gen-l10n explicados

Use um único gerador de localização e deixe explícitos os locais de entrada e saída. O exemplo abaixo pressupõe um aplicativo Flutter existente, com suas próprias restrições de SDK e configuração de projeto padrão.

Mescle as entradas relevantes no pubspec.yaml; não duplique as seções dependencies ou flutter:

dependencies:
  flutter:
    sdk: flutter
  flutter_localizations:
    sdk: flutter
  intl: any

flutter:
  generate: true

Resolva as dependências com flutter pub get. A entrada intl: any segue o padrão oficial de configuração, permitindo que a resolução de dependências selecione a versão compatível com o SDK do Flutter; mantenha o lockfile do aplicativo e o processo normal de revisão de dependências.

Crie o l10n.yaml na raiz do projeto:

arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart

Use o guia de internacionalização do Flutter atual para a configuração específica do SDK. No processo moderno, os arquivos de localização gerados ficam na árvore de código-fonte do aplicativo. O exemplo importa de lib/l10n; evite copiar uma importação sintética antiga de package:flutter_gen para uma nova configuração. Veja a nota de migração do código gerado.

Crie o lib/l10n/app_en.arb:

{
  "@@locale": "en",
  "appTitle": "Reading room",
  "@appTitle": {
    "description": "Title of the sample reading application"
  },
  "welcomeName": "Welcome, {name}",
  "@welcomeName": {
    "description": "Greeting on the home screen",
    "placeholders": {
      "name": {"type": "String", "example": "Sam"}
    }
  },
  "savedBooks": "{count, plural, =0{No saved books} one{1 saved book} other{{count} saved books}}",
  "@savedBooks": {
    "description": "Number of books saved to the user's library",
    "placeholders": {
      "count": {"type": "int"}
    }
  },
  "readingState": "{state, select, active{Reading now} paused{Reading paused} other{Ready to read}}",
  "@readingState": {
    "description": "Reading status; state is active, paused or another value",
    "placeholders": {
      "state": {"type": "String"}
    }
  }
}

Crie o lib/l10n/app_es.arb:

{
  "@@locale": "es",
  "appTitle": "Sala de lectura",
  "welcomeName": "Te damos la bienvenida, {name}",
  "savedBooks": "{count, plural, =0{No hay libros guardados} one{1 libro guardado} other{{count} libros guardados}}",
  "readingState": "{state, select, active{Leyendo ahora} paused{Lectura en pausa} other{Todo listo para leer}}"
}

O modelo contém os metadados de placeholders usados pelo gerador. O arquivo localizado preserva as chaves das mensagens, os nomes dos placeholders e os identificadores de select, alterando apenas a redação exibida ao usuário. Estes exemplos em espanhol ilustram o mecanismo; o texto de produção deve passar por revisão nativa no contexto real do produto.

Execute flutter gen-l10n depois de adicionar ou alterar recursos. Trate os erros do gerador como problemas de recursos que exigem ação e resolva-os antes de integrar os arquivos a um release.

O exemplo a seguir deve ficar em lib/main.dart depois da geração:

import 'package:flutter/material.dart';
import 'l10n/app_localizations.dart';

void main() => runApp(const ReadingApp());

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      localizationsDelegates: AppLocalizations.localizationsDelegates,
      supportedLocales: AppLocalizations.supportedLocales,
      home: const ReadingHome(),
    );
  }
}

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

  @override
  Widget build(BuildContext context) {
    final messages = AppLocalizations.of(context)!;
    return Scaffold(
      appBar: AppBar(title: Text(messages.appTitle)),
      body: Padding(
        padding: const EdgeInsetsDirectional.all(16),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            Text(messages.welcomeName('Sam')),
            Text(messages.savedBooks(3)),
            Text(messages.readingState('active')),
          ],
        ),
      ),
    );
  }
}

A API gerada deixa visível no código a diferença entre uma mensagem simples e uma mensagem com argumentos. appTitle é acessado como um valor; welcomeName, savedBooks e readingState recebem os valores necessários para montar suas mensagens.

Consulte a documentação do easy_localization e a documentação do GetX atuais antes de escolher. Teste o comportamento de fallback, os parâmetros, as categorias de plural e os processos de extração com suas mensagens reais. Uma API prática para strings em inglês não comprova a cobertura de todos os idiomas que você pretende lançar.

O intl não é uma plataforma concorrente de gestão de traduções. Ele fornece utilitários de internacionalização usados pelos processos de localização. O gen-l10n gera acessores do aplicativo a partir de recursos ARB. O pacote intl_utils, separado, também gera código de localização, mas sua página estava marcada como descontinuada quando verificada em 30 de outubro de 2026. Verifique o status de manutenção antes de adotá-lo em um novo projeto.

Use uma matriz de testes prática:

O FAQ do Flutter para web descreve o foco em experiências de aplicativo e recomenda uma abordagem orientada a documentos para conteúdo web estático e rico em texto. Considere páginas separadas em HTML para marketing, ajuda e conteúdo editorial quando elas precisarem ter bom desempenho na busca orgânica.

Mantenha a terminologia alinhada entre o app e essas páginas públicas. Quem chega pela busca deve reconhecer o nome do recurso ao passar da landing page localizada para o aplicativo, mesmo quando as duas superfícies usam sistemas de renderização diferentes.

Os formatos de projetos de software documentados pelo Smartcat incluem importações de JSON, YAML, XML do Android, .strings do iOS e LocJSON. A documentação consultada para este guia não confirma suporte nativo a ARB nem um processo testado de conversão de ARB para JSON. Não presuma que mudar a extensão de um arquivo comprova a compatibilidade. Consulte a documentação de projetos de software.

Use o roteiro a seguir como um procedimento de validação proposto, junto com sua equipe de implementação, e não como uma receita de conector já testada: