---

name: flutter-localization description: Add Flutter translation assets, locale initialization, localized strings, locale switching, and plurals with easy_localization and CSV or JSON files. Use for Flutter i18n work; not RTL-only layout or locale-specific date formatting. metadata: triggers: files: - '/assets/translations/*.json' - '/assets/langs/*.csv' - 'main.dart' keywords: - localization - multi-language - translation - tr() - easy_localization - sheet_loader

Localization

Priority: P1 (HIGH)

Format Selection

• CSV (Recommended for teams with translators): Google Sheets compatibility via sheet_loader_localization. Store in assets/langs/.
• JSON (Developer-friendly): Nested structure support with IDE validation. Store in assets/translations/.

Scope Boundary

• Use this skill for translation assets, EasyLocalization bootstrap, .tr(), plural(), and a language/locale switcher.
• Do not use it for RTL-only widget direction, typography, or locale-aware date/number formatting when translation assets are unchanged.

Structure

# CSV Format (Google Sheets workflow)
assets/langs/langs.csv

# OR JSON Format (nested keys)
assets/translations/
├── en.json
└── vi.json

Implementation Workflow

1. Initialize — Call await EasyLocalization.ensureInitialized() before runApp.
2. Wrap root — Wrap app with EasyLocalization widget specifying supported locales and path.
3. Translate strings — Use .tr() extension on keys (e.g., 'welcome'.tr()). For dynamic text, use 'welcome_user'.tr(namedArgs: {'name': 'John'}) with a {name} placeholder, or pass positional args:.
4. Switch locale — Change via context.setLocale(Locale('vi')).
5. Handle plurals — Use plural() for quantity-dependent strings, such as item_count or cart keys.
6. Sync translations — Use sheet_loader_localization to auto-generate CSV/JSON from Google Sheets.

Bootstrap & Usage Examples

See implementation examples for bootstrap setup and translation usage patterns.

Anti-Patterns

• No Hardcoded Strings: Always use translation keys from assets
• No Manual Localization Calls: Use easy_localization .tr() extension
• No Mismatched Keys: Ensure keys identical across all locale-specific files

Reference & Examples

For setup and Google Sheets automation: See references/REFERENCE.md.

Related Topics

idiomatic-flutter | widgets