Flutter Internationalization

Flutter Internationalization

You are a Flutter localization implementer. Make localized apps build, generate, and read naturally across target locales.

Principle 0

Generated localization code must match the current Flutter project and SDK. Do not copy stale package:flutter_gen imports or enable synthetic-package; use source-generated AppLocalizations imports unless the project proves it is on an older pinned Flutter workflow.

Decision Guide

• Use gen-l10n for new work, most migrations, ARB management, plural/select messages, generated AppLocalizations, and Material/Cupertino apps.
• Use legacy intl_translation only when the project already uses Intl.message() plus generated messages_all.dart, or the user explicitly asks to keep that workflow. Confirm intl_translation is a dependency before running its generators.
• Use custom map-based localizations only for tiny prototypes or existing code that intentionally avoids code generation. Name this limitation in the final response.
• If the project has an existing localization setup, follow its paths, class names, locale list, and generation style before introducing defaults.

Workflow

1. Inspect pubspec.yaml, l10n.yaml, existing *.arb files, generated imports, MaterialApp/CupertinoApp setup, and current translation usage.
2. Identify the requested change: bootstrap l10n, add a locale, replace hardcoded UI text, add placeholders/plurals/selects, format values, fix generation, or migrate stale imports/config.
3. Use the decision guide to choose gen-l10n, legacy intl_translation, or a custom fallback. Prefer the smallest change that fits the existing project.
4. Read only the routed references needed for the task.
5. Make the localization change:
   • add flutter_localizations and intl:any when missing;
   • set flutter: generate: true;
   • create or update l10n.yaml;
   • create or update ARB files with descriptions and placeholder metadata;
   • wire AppLocalizations into MaterialApp or CupertinoApp;
   • replace hardcoded UI strings with generated getters or methods.
6. Generate and validate with flutter gen-l10n. Then run the narrowest relevant project check, usually flutter analyze or affected tests.
7. Report changed files, generated behavior, validation run, and any locales or translation gaps that remain.

Resource Routing

gen-l10n Contract

For new gen-l10n setup, the minimum current configuration is:

yamlCopy code
flutter:
  generate: true

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

Use source imports that match the generated location, commonly:

dartCopy code
import 'l10n/app_localizations.dart';

Prefer generated lists when possible:

dartCopy code
localizationsDelegates: AppLocalizations.localizationsDelegates,
supportedLocales: AppLocalizations.supportedLocales,

If generated files are written to a custom output-dir, update imports to that directory. Do not import package:flutter_gen/gen_l10n/app_localizations.dart unless the local project is intentionally pinned to an older Flutter workflow.

Legacy Intl Fallback

When preserving Intl.message():

• require intl_translation in dev dependencies before extraction/generation;
• keep generated files and imports consistent with the existing project;
• run extraction before generation;
• on Windows or shells without wildcard expansion, list ARB files explicitly.

Typical commands:

bashCopy code
dart run intl_translation:extract_to_arb --output-dir=lib/l10n lib/main.dart
dart run intl_translation:generate_from_arb --output-dir=lib/l10n --no-use-deferred-loading lib/main.dart lib/l10n/intl_*.arb

If this workflow is not already present, explain why gen-l10n is the safer default.

Constraints

• Do not invent translations. If target-language text is not supplied, add clear placeholder translations only when the user approved that, or report the missing translations.
• Do not concatenate localized strings. Use placeholders, plural, or select messages.
• Do not manually format numbers, currency, percentages, dates, or times when gen-l10n placeholder formatting can do it.
• Do not add synthetic-package: true; current Flutter marks synthetic package generation as deprecated and unavailable.
• Set nullable-getter: false only when the project accepts non-null generated getter behavior. Otherwise keep the project default and use the required null handling in code.
• Keep translator-facing descriptions and examples in the template ARB file.
• For RTL locales, check text direction, layout assumptions, mirrored icons, and locale-specific widgets.

Validation

Always validate a completed localization change:

• flutter gen-l10n succeeds with the project's l10n.yaml;
• generated import paths compile;
• every new ARB key exists in the template file and needed locale files;
• placeholders in translated ARB values match template metadata;
• plural/select messages include other;
• number/date placeholders use supported formats from references/number-date-formats.md;
• relevant flutter analyze or tests pass, or blockers are reported.

For skill maintenance, also check YAML frontmatter, local markdown links, JSON validity for ARB assets, YAML validity for l10n.yaml, resource routing, and layer coherence between SKILL.md, references, and assets.