Skip to content
Skills Library
Programming · Building & coding

internationalization

/internationalization

Best practices for internationalization (i18n) and localization (l10n) in Flutter, using the built-in `flutter_localizations` and `intl` setup with ARB files as the single source of truth. Use when adding, modifying, or reviewing ARB translations, locale setup (`l10n.yaml`, `generate: true` in `pubspec.yaml`, `flutter gen-l10n`, `localizationsDelegates`, `supportedLocales`), BuildContext l10n extensions such as `context.l10n`, hardcoded user-facing strings that should be localized, localized strings passed into shared or reusable widgets, or RTL/directional layout support with `EdgeInsetsDirec

Licence
MIT
Last repository change
20.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
5
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 20.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Best practices for internationalization (i18n) and localization (l10n) in Flutter, using the built-in `flutter_localizations` and `intl` setup with ARB files as the single source of truth. Use when adding, modifying, or reviewing ARB translations, locale setup (`l10n.yaml`, `generate: true` in `pubspec.yaml`, `flutter gen-l10n`, `localizationsDelegates`, `supportedLocales`), BuildContext l10n extensions such as `context.l10n`, hardcoded user-facing strings that should be localized, localized strings passed into shared or reusable widgets, or RTL/directional layout support with `EdgeInsetsDirec

Original author description

Best practices for internationalization (i18n) and localization (l10n) in Flutter, using the built-in `flutter_localizations` and `intl` setup with ARB files as the single source of truth. Use when adding, modifying, or reviewing ARB translations, locale setup (`l10n.yaml`, `generate: true` in `pubspec.yaml`, `flutter gen-l10n`, `localizationsDelegates`, `supportedLocales`), BuildContext l10n extensions such as `context.l10n`, hardcoded user-facing strings that should be localized, localized strings passed into shared or reusable widgets, or RTL/directional layout support with `EdgeInsetsDirec

How it works

  1. Core Standards
  2. Setup Pipeline and ARB File Format
  3. BuildContext Extension
  4. Reusable Widget Strategy
  5. Text Directionality
  6. Backend Considerations
  7. Common Patterns
  8. Additional Resources
Original SKILL.md headings · 121 lines, 683 words
SKILL.md preview
---
name: internationalization
description: >
  Best practices for internationalization (i18n) and localization (l10n) in Flutter, using the
  built-in `flutter_localizations` and `intl` setup with ARB files as the single source of
  truth. Use when adding, modifying, or reviewing ARB translations, locale setup (`l10n.yaml`,
  `generate: true` in `pubspec.yaml`, `flutter gen-l10n`, `localizationsDelegates`,
  `supportedLocales`), BuildContext l10n extensions such as `context.l10n`, hardcoded
  user-facing strings that should be localized, localized strings passed into shared or
  reusable widgets, or RTL/directional layout support with `EdgeInsetsDirectional`. Also use
  when asked to add or configure any third-party i18n or translation package
  (easy_localization, slang, flutter_i18n, or intl_utils), and when shipping or fixing a
  screen for a right-to-left language such as Arabic, Hebrew, Farsi, or Urdu,
  including mirroring padding, alignment, icons, or images, and replacing `EdgeInsets`
  left/right.
allowed-tools: Read Glob Grep
---

# Internationalization

Internationalization (i18n) and localization (l10n) best practices for Flutter applications using Flutter's built-in localization system with ARB files as the single source of truth.

## Core Standards

Apply these standards to all internationalization work:

- **Never hardcode user-facing strings** — all text must go through the l10n system
- **Use Flutter's built-in localization system** — `flutter_localizations` + `intl`, never third-party i18n libraries
- **ARB files are the single source of truth** for all translations
- **`BuildContext` extension for cleaner l10n access** — use `context.l10n` instead of `AppLocalizations.of(context)`
- **Pass localized strings as parameters to reusable widgets** — never couple shared widgets directly to `AppLocalizations`
- **Use `EdgeInsetsDirectional` (start/end) instead of `EdgeInsets` (left/right)** — ensures correct layout in RTL languages
- **Handle RTL layout properly** — use directional widgets for padding, positioning, and alignment
- **Implement i18n early** — even if only one language is planned initially, the overhead is small and the long-term benefit is significant
- **Dart 3.13 primary constructors** — on a Dart 3.13+ baseline, declare a reusable widget's localized-string fields as primary-constructor declaring parameters (`class const ConfirmDialog({required final String title, super.key}) extends StatelessWidget`) rather than `this.field`; keep the classic form only below 3.13

## Setup Pipeline and ARB File Format

Add `flutter_localizations` and `intl` as dependencies, enable `generate: true` in `pubspec.yaml`, configure `l10n.yaml`, create ARB files in `lib/l10n/arb/`, run `flutter gen-l10n`, and wire up `MaterialApp` with `localizationsDelegates` and `supportedLocales`. ARB files support simple strings, placeholders, and ICU plural syntax.

## BuildContext Extension

Create an extension for ergonomic l10n access throughout the codebase:

```dart
extension AppLocalizationsX on BuildContext {
  AppLocalizations get l10n => AppLocalizations.of(this);
}
```

Usage:

```dart
// Preferred
Text(context.l10n.helloWorld);

// Avoid
Text(AppLocalizations.of(context).helloWorld);
```

## Reusable Widget Strategy

Shared widgets that live in separate packages should not depend on `AppLocalizations` directly. Instead, pass localized strings as constructor parameters:

When someone asks to add `AppLocalizations` to a shared package, decline and say why — the package would carry its own translations and every consuming app would be locked to them — then rewrite their widget with the label as a `final String` constructor parameter and show the call site supplying `context.l10n`. Give both as Dart code; describing the change in prose leaves the caller to guess the signature.

```dart
// Shared widget — no l10n dependency
class const ConfirmDialog({
  required final String title,
  required final String message,
  required final String confirmLabel,
  required final String cancelLabel,
  super.key,
}) extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return AlertDialog(
      title: Text(title),
      content: Text(message),
      actions: [
        TextButton(onPressed: () => Navigator.pop(context), child: Text(cancelLabel)),
        FilledButton(onPressed: () => Navigator.pop(context, true), child: Text(confirmLabel)),
      ],
    );
  }
}

// App-level usage — passes localized strings
showDialog<bool>(
  context: context,
  builder: (_) => ConfirmDialog(
    title: context.l10n.deleteTitle,
    message: context.l10n.deleteMessage,
    confirmLabel: context.l10n.confirm,
    cancelLabel: context.l10n.cancel,
  ),
);
```

## Text Directionality

Use `EdgeInsetsDirectional` (start/end) instead of `EdgeInsets` (left/right) for all padding and margins. Use directional widget variants (`PositionedDirectional`, `AlignDirectional`, `BorderDirectional`) for RTL-aware layouts. Icons mirror automatically in RTL; images require `matchTextDirection: true`.

## Backend Considerations

Store backend content with per-locale translations and require clients to transmit the user's locale. For error messages, map HTTP status codes or custom backend error constants to l10n keys on the frontend.

## Common Patterns

### Adding a New Locale

1. Create `app_<locale>.arb` in `lib/l10n/arb/` (e.g., `app_fr.arb`)
2. Add translations for all keys from the template ARB file
3. Run `flutter gen-l10n`
4. The new locale is automatically available through `AppLocalizations.supportedLocales`

### Adding a New String

1. Add the key-value pair to the template ARB file (`app_en.arb`)
2. Add the `@key` metadata with description and placeholders if needed
3. Add translations in all other ARB files
4. Run `flutter gen-l10n`
5. Use via `context.l10n.newKey`

### Pluralization

1. Define the plural string in the template ARB file using ICU message syntax
2. Provide placeholder metadata with `"type": "int"`
3. Add plural forms in all locale ARB files
4. Use via `context.l10n.itemCount(items.length)`

## Additional Resources

- [references/setup.md](references/setup.md) — full step-by-step setup pipeline and ARB file format examples
- [references/directionality.md](references/directionality.md) — visual vs directional widgets, icon/image mirroring, Material bidirectionality standards
- [references/backend.md](references/backend.md) — multi-language content storage and error message localization
Files in this package (5)
  • SKILL.md 6 KB
  • agents/openai.yaml 1 KB
  • references/backend.md 1 KB
  • references/directionality.md 2 KB
  • references/setup.md 2 KB

Versions

RepositoryScoreLicence
This page · verygoodopensource/vgv-ai-flutter-plugin100MIT
builderio/agent-native100MIT
builderio/agent-native100MIT
rampstackco/claude-skills100MIT
reddygopalkrishna/developer-agent-skills100MIT
thaithienvanid/aidd85Apache-2.0

Database snapshot: 13.11.2026 · package version c3dd994eeb79 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100flutter-internationalization
    Add, fix, audit, and maintain Flutter internationalization with gen-l10n, ARB files, AppLocalizations, flutter_localizations, intl formatting, plural/select messages, RTL support, locale-specific number/date formatting, and localization build errors. Use when asked to add l10n…
  • 100flutter-setup-localization
    Add `flutter_localizations` and `intl` dependencies, enable "generate true" in `pubspec.yaml`, and create an `l10n.yaml` configuration file. Use when initializing localization support for a new Flutter project.
  • 90flutter-localization
    Implement or review Flutter localization with gen_l10n, ARB resources, plurals, locale-aware formatting, RTL layout, and locale testing. Use for multi-language UI or localization infrastructure; not for arbitrary copy editing.
  • 90flutter-l10n-rtl
    Localization and right-to-left (Arabic, Hebrew, Persian, Urdu) rules for Flutter - easy_localization, gen-l10n/ARB, intl, slang, directional layout, number/date/currency formatting. Use when adding user-facing text, building or changing layouts in an app that supports RTL or…
  • 95setup-i18n
    Sets up server-side internationalization infrastructure for Next.js App Router using next-intl. Creates middleware locale detection, translation file structure, type-safe utilities, and routing configuration. Run before implementing use cases so that all feature code produces…
  • 100flutter-localization
    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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.