A Flutter grocery app localized with gen-l10n into English, German and Polish shows German to French-speaking users and English strings to some Polish users; what is wrong?

## Symptom 1: French users see German **Cause.** gen-l10n builds `AppLocalizations.supportedLocales` from the ARB files it finds, sorted **alphabetically** by file: `app_de.arb`, `app_en.arb`, `app_pl.arb` give `[Locale('de'), Locale('en'), Locale('pl')]`. `MaterialApp` receives that list, and when none of the user's preferred locales matches by language or country, Flutter's default resolution returns **`supportedLocales.first`**. A device set only to French therefore gets German. **Fix.** Tell the generator which locale leads: - `preferred-supported-locales: [en]` in `l10n.yaml` moves `en` to the front of the generated list, so the fallback is English. - The listed locale must have an ARB file; otherwise generation fails with an error saying the preferred locale cannot be added. - Custom resolution logic (a `localeResolutionCallback`) is another route, but for "which language is the default" the l10n option is the smallest change and keeps the default resolution intact. ## Symptom 2: Polish users see some English strings **Cause.** Developers add keys to the template `app_en.arb` faster than translations arrive. For every key missing from `app_pl.arb`, gen-l10n **uses the template's message** in the generated Polish class and records the key as untranslated. Nothing fails: the console shows a summary such as `"pl": 3 untranslated message(s).` and suggests the report option. **Fix.** Make the gap visible and blocking: 1. Add `untranslated-messages-file: build/untranslated.json` (any path) to `l10n.yaml`. The tool writes a JSON object mapping each locale to its missing message ids, or `{}` when complete. 2. In CI, run `flutter gen-l10n` and fail the job when that file is not `{}`. 3. Optionally set `required-resource-attributes: true`, so every message must carry an `@` metadata entry, the natural home for a translator description. Regional files follow the same rule with one refinement: a key missing from `app_de_AT.arb` but present in `app_de.arb` is inherited from the German class and not reported. ## Symptom 3 (often found at the same time): Material widgets fail in German and Polish If the app wires only `AppLocalizations.delegate`, your strings are Polish but nothing supplies `MaterialLocalizations` for `pl`. The framework's built-in `DefaultMaterialLocalizations` supports only English, so in a debug build Flutter reports *"This application's locale, pl, is not supported by all of its localization delegates"*, and widgets that need localized labels (the back button tooltip, date pickers, text-selection menus) fail with *"No MaterialLocalizations found."* **Fix.** Pass `AppLocalizations.localizationsDelegates`, which already includes `GlobalMaterialLocalizations.delegate`, `GlobalCupertinoLocalizations.delegate` and `GlobalWidgetsLocalizations.delegate`. Delegate order matters only when two delegates serve the same type: the first one that supports the locale wins. Two related checks belong in the same review: - **Regional files.** If marketing later adds `app_de_AT.arb`, the generated list gains `de_AT`, and Austrian devices resolve to it; make sure it only overrides what differs and inherits the rest from `app_de.arb`. - **iOS language list.** The App Store listing reads the languages declared in the Xcode project, which gen-l10n does not edit; add German and Polish there as well. ## Diagnosing in order | Check | How | What a healthy app shows | |---|---|---| | Order of `supportedLocales` | Read the generated `app_localizations.dart` | The intended default first | | Untranslated keys | `flutter gen-l10n` output or the JSON report | No untranslated messages | | Framework delegates | `MaterialApp.localizationsDelegates` | The generated list, or a superset | | Runtime locale | `Localizations.localeOf(context)` in a debug overlay | The locale you expect per device | ## Testing it - A widget test can pump `MaterialApp` with `locale: const Locale('fr')` and the generated lists, then assert English text, which pins the fallback. - Another can pump `Locale('pl')` and a `showDatePicker` call to prove Material labels load. - Keep a CI step that fails on a non-empty untranslated report, so the next new key cannot ship half-translated. ## Why it matters for a store release Users judge a localized app by its worst screen. Falling back to the wrong language, or mixing English into Polish checkout screens, reads as a broken app; both issues are configuration, and both are cheap to lock down with the two `l10n.yaml` options and one CI check.