Flutter LocalizationSAFE

A collection of Agent Skills Standard and Best Practice for Programming Languages, Frameworks that help our AI Agent follow best practies on frameworks and programming laguages

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
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

```text
# 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](references/implementation.md) 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](references/REFERENCE.md).

## Related Topics

idiomatic-flutter | widgets

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.