--- name: flutter-internationalization description: >- 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 or i18n, translate Flutter UI text, configure l10n.yaml, manage ARB translations, migrate away from package:flutter_gen imports, or troubleshoot generated localization code. metadata: author: Stanislav [MADTeacher] Chernyshev version: "2.0" --- # 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 | Task | Read or use | Why | |---|---|---| | Configure or debug `l10n.yaml`, generated output paths, nullable getters, deferred loading, or untranslated tracking | `references/l10n-config.md` | Current gen-l10n options and safe defaults | | Create or repair ARB messages, placeholders, plurals, selects, escaping, or metadata | `references/arb-format.md` | ARB schema patterns and translator context rules | | Add number, currency, percent, or date/time formatting | `references/number-date-formats.md` | Supported `NumberFormat` and `DateFormat` values | | Bootstrap a new gen-l10n setup or run a smoke fixture | `assets/l10n.yaml`, `assets/app_en.arb` | Reusable minimal templates | ## gen-l10n Contract For new gen-l10n setup, the minimum current configuration is: ```yaml flutter: generate: true ``` ```yaml 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: ```dart import 'l10n/app_localizations.dart'; ``` Prefer generated lists when possible: ```dart 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: ```bash 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. --- Source attribution: MADTeacher Original project: https://github.com/MADTeacher/mad-agents-skills/blob/2fb67e384c6d91f32025bd96400d33b73f21bdc7/flutter-internationalization/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Copyright (c) 2026 Stanislav Chernyshev Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Mega AI Hub resource metadata Creator / publisher: MADTeacher Original project: https://github.com/MADTeacher/mad-agents-skills/blob/2fb67e384c6d91f32025bd96400d33b73f21bdc7/flutter-internationalization/SKILL.md Attribution basis: Recovered original package and original project license at a pinned revision Fields of work: Development & Engineering, Product Management Roles: Frontend Developer, Mobile Developer, Product Manager Specialties: Frontend, Mobile Tools: Tool not specified Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 3d2c8764754f21b6b80a5b81309ce52e3f22e0c006b87e80b90b97b8b181bf23 Metadata reviewed: 2026-10-27 This metadata supersedes earlier Mega AI Hub catalog attribution. Original instruction and supporting files are preserved.