Flutter gen_l10n, ARB & Locale Switching Guide

How do you translate a Flutter app with gen_l10n and ARB files so that language switching, plural messages, dynamic text and accessible controls still work? People searching Flutter localization tutorial, AppLocalizations, Flutter ARB plurals or multilingual Dart app setup need more than a list of packages. They need to know what the generated messages do, which values they must never change and how to test the actual app after a locale changes.

Flutter uses localization delegates and locale resolution in its widget environment. The Flutter gen_l10n tool can generate typed Dart accessors from ARB resources, while flutter_localizations helps localize framework components. The generated class does not decide product policy, create correct translations or guarantee that a device has the fonts, layout or data required by the chosen language.

This guide follows a complete application journey: project setup, ARB metadata, placeholders, ICU plural messages, widget context, locale persistence, formatting, RTL behavior, accessibility, platform packaging and release tests. The goal is a mobile or desktop experience that readers can trust through sign-in, forms, errors, purchases and help pages—not a translated home-screen screenshot.

Quick answer: what must work for the reader

Successful Flutter gen_l10n and ARB localization localization requires four agreements: the language a visitor expects, the message resources the application actually loads, the behavior promised by those messages and the proof that a person can complete the task. The translation source is locale-specific ARB JSON files such as app_en.arb and app_es.arb, with metadata describing arguments; the application reads it through Flutter localization delegates, supportedLocales and generated AppLocalizations accessors. Neither fact guarantees that the next screen is correct. Start with one complete task and verify the exact response, not just the presence of another language in a menu.

For a first review, identify the real user’s locale choice, the primary action, a likely failure, one changing count, one sensitive date or amount, and a final confirmation. A multilingual product is good when the reader understands what happened, can take the next step and has not been misled about the resulting state. The rest of this guide explains how to reach that result methodically without relying on literal word-for-word substitution.

Contents and how to use this guide

How the platform translates an actual user journey
Twelve foundations for reliable localization
Eighteen realistic failure patterns and how to repair them
A release plan that can be checked by a reader
Frequently asked questions and primary documentation

How Flutter gen_l10n and ARB localization works in practice

Flutter presents user interface through widgets. Localization delegates supply translated resources for a selected Locale, and dependent widgets can rebuild when that locale changes. ARB files store message values and optional metadata such as placeholder descriptions. gen_l10n creates a strongly typed interface for those messages. This flow translates presentation text, not server-side state, the device’s time zone, a payment amount or permission logic.

Begin with the source layer: Dart widgets that call generated AppLocalizations members inside the right BuildContext. A translator should know what each string means on the page, the audience it addresses and the user action it describes. A developer should know the complete lookup path from that source through locale-specific ARB JSON files such as app_en.arb and app_es.arb, with metadata describing arguments to Flutter localization delegates, supportedLocales and generated AppLocalizations accessors. A reviewer should know which persistent facts, such as permission, money, identity or deadline, remain untouched. Those are three different kinds of correctness, and a project needs all of them.

The language-selection path is a user-visible language preference that persists through app navigation and restart. Treat that path as a product requirement. It is not enough for a technical library to recognize a locale identifier: the effective choice must survive the places where a person expects continuity, including direct navigation and errors. Unsupported preferences deserve deliberate behavior. If the system only has part of an edition, state that limitation and avoid claiming the complete task is available in the target language.

One useful way to investigate a localization fault is to move from symptom to evidence. First read what the person saw, then find the message or component that produced it, then determine which locale was effective, and finally reproduce the relevant state. This prevents changing a translation to compensate for an entirely different bug, such as stale cache, incorrect authorization or a wrong time zone.

Twelve foundations that make a multilingual release dependable

1. Separate language choice from translated content

A language preference is a request about presentation, not a license to change the user’s data or permissions. In Flutter gen_l10n and ARB localization, that means checking Add flutter_localizations and the generation configuration documented for the installed Flutter release. Confirm the import location of generated code rather than copying old synthetic-package examples blindly. Do not confuse an available translation mechanism with a complete language edition. A message only helps readers when its wording matches the current feature state and remains available at the point of use.

Trace one user account from initial visit to a saved preference. A translated label and the value it represents must still agree after sign-in, sign-out and refresh. For this foundation, record one example of correct behavior and one intentionally incorrect state. A reliable review can distinguish the two without knowing the source code. Include a clean-session result, the effective locale and the wording the user actually received. This makes future corrections specific and prevents a configuration change from being mistaken for evidence of comprehension.

2. Describe a locale policy before configuring a library

A locale is more than two letters. Language, region, numbering, time conventions and script direction may matter separately. In Flutter gen_l10n and ARB localization, that means checking Set the Flutter generate flag, configure l10n.yaml where needed, and treat the template ARB as the source message inventory that language editions must track. Do not confuse an available translation mechanism with a complete language edition. A message only helps readers when its wording matches the current feature state and remains available at the point of use.

List supported variants and test one unavailable variant deliberately. Do not imply that a regional edition exists merely because a neutral-language fallback can display. For this foundation, record one example of correct behavior and one intentionally incorrect state. A reliable review can distinguish the two without knowing the source code. Include a clean-session result, the effective locale and the wording the user actually received. This makes future corrections specific and prevents a configuration change from being mistaken for evidence of comprehension.

3. Give messages stable, meaningful context

The same English verb can name an action, a document or a machine state; translators need its purpose. In Flutter gen_l10n and ARB localization, that means checking ARB metadata beginning with @ can describe text meaning and the expected type of placeholders; translators need this context for short or ambiguous strings. Do not confuse an available translation mechanism with a complete language edition. A message only helps readers when its wording matches the current feature state and remains available at the point of use.

Write explanatory comments for short buttons, errors and dynamic fragments. A reviewer should know the user’s task, not infer meaning from a string key. For this foundation, record one example of correct behavior and one intentionally incorrect state. A reliable review can distinguish the two without knowing the source code. Include a clean-session result, the effective locale and the wording the user actually received. This makes future corrections specific and prevents a configuration change from being mistaken for evidence of comprehension.

4. Protect plural forms and placeholders

Some languages use plural categories not found in English; variables must survive translation and remain correctly associated. In Flutter gen_l10n and ARB localization, that means checking Use plural messages as complete grammatical units, not as concatenated singular suffixes. ICU-style placeholders must preserve correct argument references and format. Do not confuse an available translation mechanism with a complete language edition. A message only helps readers when its wording matches the current feature state and remains available at the point of use.

Test counts of zero, one, two and a larger value where the language requires it. Check named or positional tokens and confirm that interpolated text cannot create markup. For this foundation, record one example of correct behavior and one intentionally incorrect state. A reliable review can distinguish the two without knowing the source code. Include a clean-session result, the effective locale and the wording the user actually received. This makes future corrections specific and prevents a configuration change from being mistaken for evidence of comprehension.

5. Treat dates, amounts and numbers as data

Changing a language is not changing a stored balance, measurement, time instant or contractual quantity. In Flutter gen_l10n and ARB localization, that means checking AppLocalizations.of(context) requires an appropriate context beneath localization-enabled widgets; startup code may not yet have that context. Do not confuse an available translation mechanism with a complete language edition. A message only helps readers when its wording matches the current feature state and remains available at the point of use.

Compare internal values before and after switching locale. Date and currency formatting should be intentional, but currency conversion requires a separate authorized calculation. For this foundation, record one example of correct behavior and one intentionally incorrect state. A reliable review can distinguish the two without knowing the source code. Include a clean-session result, the effective locale and the wording the user actually received. This makes future corrections specific and prevents a configuration change from being mistaken for evidence of comprehension.

6. Test the complete task rather than isolated sentences

A perfect landing page is of little use if the confirmation, help page or error screen reverts to another language. In Flutter gen_l10n and ARB localization, that means checking MaterialApp or the relevant app shell needs supported locales and delegates so both app strings and framework components can render in the chosen language. Do not confuse an available translation mechanism with a complete language edition. A message only helps readers when its wording matches the current feature state and remains available at the point of use.

Follow a realistic journey with a clean browser state. Include a user who cannot sign in, a user with a saved preference and a user whose language lacks some messages. For this foundation, record one example of correct behavior and one intentionally incorrect state. A reliable review can distinguish the two without knowing the source code. Include a clean-session result, the effective locale and the wording the user actually received. This makes future corrections specific and prevents a configuration change from being mistaken for evidence of comprehension.

7. Design a transparent fallback for missing translations

Fallback is sometimes necessary, but it can conceal a dangerous gap when important wording stays untranslated. In Flutter gen_l10n and ARB localization, that means checking Changing the selected locale may rebuild dependent widget trees; persistent user choice and device preference should follow a clear priority policy. Do not confuse an available translation mechanism with a complete language edition. A message only helps readers when its wording matches the current feature state and remains available at the point of use.

Define what must block release, what may show a clear fallback and what should display a language-availability notice. A silent fallback is not equivalent to reviewed content. For this foundation, record one example of correct behavior and one intentionally incorrect state. A reliable review can distinguish the two without knowing the source code. Include a clean-session result, the effective locale and the wording the user actually received. This makes future corrections specific and prevents a configuration change from being mistaken for evidence of comprehension.

8. Keep markup, layout and assistive text readable

Long words, right-to-left text, fonts, focus order and accessible names can change whether an interface actually works. In Flutter gen_l10n and ARB localization, that means checking The language of a message and the region of a numeric format are related but not identical decisions. A currency symbol, amount and exchange rate have different meanings. Do not confuse an available translation mechanism with a complete language edition. A message only helps readers when its wording matches the current feature state and remains available at the point of use.

Enlarge text and use keyboard navigation. Inspect buttons, dialogs, alternative text and screen-reader announcements in context; do not judge by screenshots alone. For this foundation, record one example of correct behavior and one intentionally incorrect state. A reliable review can distinguish the two without knowing the source code. Include a clean-session result, the effective locale and the wording the user actually received. This makes future corrections specific and prevents a configuration change from being mistaken for evidence of comprehension.

9. Make translation changes reviewable and reversible

Translations need source version, reviewer, approval status and a way to see semantic changes over time. In Flutter gen_l10n and ARB localization, that means checking Text scaling, widget width, line breaks and right-to-left direction are interaction concerns. A long translation may need flexible layout rather than shortening its meaning. Do not confuse an available translation mechanism with a complete language edition. A message only helps readers when its wording matches the current feature state and remains available at the point of use.

Retain examples that distinguish an old instruction from a revised one. A small tracked correction is more reliable than replacing the entire language file without context. For this foundation, record one example of correct behavior and one intentionally incorrect state. A reliable review can distinguish the two without knowing the source code. Include a clean-session result, the effective locale and the wording the user actually received. This makes future corrections specific and prevents a configuration change from being mistaken for evidence of comprehension.

10. Release localizations as a tested product feature

The production environment may behave differently from a developer preview because of caching, bundling or missing language assets. In Flutter gen_l10n and ARB localization, that means checking Generated localizations belong to a build and packaging process. Clean release testing should reveal missing artifacts, missing font glyphs and unsupported device variants. Do not confuse an available translation mechanism with a complete language edition. A message only helps readers when its wording matches the current feature state and remains available at the point of use.

Test the deployed artifact, not only a local build. Record a reproducible route, the selected locale, the observed words and the underlying action before declaring success. For this foundation, record one example of correct behavior and one intentionally incorrect state. A reliable review can distinguish the two without knowing the source code. Include a clean-session result, the effective locale and the wording the user actually received. This makes future corrections specific and prevents a configuration change from being mistaken for evidence of comprehension.

11. Document who decides meaning when sources conflict

Technical teams own behavior, language professionals own fluency and product owners own what the service promises. In Flutter gen_l10n and ARB localization, that means checking Add flutter_localizations and the generation configuration documented for the installed Flutter release. Confirm the import location of generated code rather than copying old synthetic-package examples blindly. Do not confuse an available translation mechanism with a complete language edition. A message only helps readers when its wording matches the current feature state and remains available at the point of use.

Escalate a disputed statement with the source wording and real behavior. Do not let a smooth paraphrase hide uncertainty about a deadline, permission, safety condition or charge. For this foundation, record one example of correct behavior and one intentionally incorrect state. A reliable review can distinguish the two without knowing the source code. Include a clean-session result, the effective locale and the wording the user actually received. This makes future corrections specific and prevents a configuration change from being mistaken for evidence of comprehension.

12. Measure user success, not only message coverage

A catalog can be fully populated while readers still abandon a multilingual task. In Flutter gen_l10n and ARB localization, that means checking Set the Flutter generate flag, configure l10n.yaml where needed, and treat the template ARB as the source message inventory that language editions must track. Do not confuse an available translation mechanism with a complete language edition. A message only helps readers when its wording matches the current feature state and remains available at the point of use.

Track the steps where language switching, search, validation, navigation or support fails. Investigate the experience before interpreting any analytics change as translation quality. For this foundation, record one example of correct behavior and one intentionally incorrect state. A reliable review can distinguish the two without knowing the source code. Include a clean-session result, the effective locale and the wording the user actually received. This makes future corrections specific and prevents a configuration change from being mistaken for evidence of comprehension.

Working examples: where translations go wrong and what to do

The following cases use the ordinary tasks that expose localization weaknesses: choosing a language, submitting forms, reading warnings, following links and returning later. The examples are diagnostic rather than fictional product guarantees. They explain the likely failure mechanism and a concrete check to perform on the version of Flutter gen_l10n and ARB localization actually installed.

1. The generated AppLocalizations import is missing

The app builds in an older tutorial’s layout but fails after a Flutter upgrade. Review the public output as if you had never seen the original project. A developer may recognize the intended behavior from code, but a visitor sees only the wording and the next available action. If the screen needs a private explanation to be understood, improve the screen itself. The visible problem is worth describing exactly before opening a translation file: write down the selected language, the route and the state in which the words appeared. That short account gives a translator and an engineer the same starting point.

Generated code locations and synthetic-package behavior differ across documented versions and configuration options. Follow the current installed Flutter documentation and configure the output path explicitly where needed. Avoid changing source data or disabling a validation rule merely to make a sentence look better. The repair should be narrow enough to explain and broad enough to cover the full interaction. If the symptom disappears only on one carefully prepared development screen, the user problem may still exist.

Delete generated artifacts, regenerate and build from a clean checkout. Re-run the relevant path after the correction, including the next action and its confirmation. Compare what the wording promises with the result that the system produces; a fluent sentence can still describe the wrong operation. Save the observed language, build and state so the fix can be checked again when the application changes.

2. The app’s language changes but a dialog stays English

The main page switches to Spanish while a validation dialog retains English labels. The safest translation proof is an observed outcome, not a claim that a file exists. Pair the translated statement with a reproducible action and note which values remain unchanged. Where a fallback appears, explain the choice rather than presenting it as a finished language edition. The visible problem is worth describing exactly before opening a translation file: write down the selected language, the route and the state in which the words appeared. That short account gives a translator and an engineer the same starting point.

The dialog text was hard-coded or captured from a context outside the refreshed localization tree. Read translated values from the appropriate localization-aware widget context when the dialog is built. Avoid changing source data or disabling a validation rule merely to make a sentence look better. The repair should be narrow enough to explain and broad enough to cover the full interaction. If the symptom disappears only on one carefully prepared development screen, the user problem may still exist.

Switch locale without restarting and exercise success and failure dialogs. Re-run the relevant path after the correction, including the next action and its confirmation. Compare what the wording promises with the result that the system produces; a fluent sentence can still describe the wrong operation. Save the observed language, build and state so the fix can be checked again when the application changes.

3. ARB metadata omits the meaning of Save

A translator interprets Save as rescue rather than storing a form. Check the boundary between content and operations. Changing a label must not create a new permission, change a price or silently substitute a different workflow. A linguistic improvement is complete only when the functional promise and the underlying action still match. The visible problem is worth describing exactly before opening a translation file: write down the selected language, the route and the state in which the words appeared. That short account gives a translator and an engineer the same starting point.

A short message key lacks a description of its action and surrounding screen. Add concise ARB descriptions and supply a screenshot or feature context for review. Avoid changing source data or disabling a validation rule merely to make a sentence look better. The repair should be narrow enough to explain and broad enough to cover the full interaction. If the symptom disappears only on one carefully prepared development screen, the user problem may still exist.

Check the actual button after translation and confirm it persists data as described. Re-run the relevant path after the correction, including the next action and its confirmation. Compare what the wording promises with the result that the system produces; a fluent sentence can still describe the wrong operation. Save the observed language, build and state so the fix can be checked again when the application changes.

4. A placeholder changes name between files

The generated localization accessor fails or a translated message shows the wrong argument. Review both ordinary and uncomfortable paths: a successful request, an invalid entry, an expired session and a denied action. The text that appears only during failure may carry the strongest obligation to be clear. Treat it as first-class content. The visible problem is worth describing exactly before opening a translation file: write down the selected language, the route and the state in which the words appeared. That short account gives a translator and an engineer the same starting point.

The localized ARB entry no longer matches the template placeholder contract. Keep keys, placeholder names and expected argument types consistent while allowing word order to change. Avoid changing source data or disabling a validation rule merely to make a sentence look better. The repair should be narrow enough to explain and broad enough to cover the full interaction. If the symptom disappears only on one carefully prepared development screen, the user problem may still exist.

Generate clean code and run a test using realistic dynamic values. Re-run the relevant path after the correction, including the next action and its confirmation. Compare what the wording promises with the result that the system produces; a fluent sentence can still describe the wrong operation. Save the observed language, build and state so the fix can be checked again when the application changes.

5. A plural works for one and two but fails for zero

A download-count banner is grammatical for one item but misleading for zero. Ask a reader who did not help build the feature to complete the task. Record where they hesitate and what they believe the control will do. That evidence often reveals a problem neither machine translation scores nor unit tests can see. The visible problem is worth describing exactly before opening a translation file: write down the selected language, the route and the state in which the words appeared. That short account gives a translator and an engineer the same starting point.

The target ICU plural message lacks a required form or an appropriate zero wording. Review target-language plural categories and provide a complete contextual message. Avoid changing source data or disabling a validation rule merely to make a sentence look better. The repair should be narrow enough to explain and broad enough to cover the full interaction. If the symptom disappears only on one carefully prepared development screen, the user problem may still exist.

Test the selected locale with zero, one, two and a representative large count. Re-run the relevant path after the correction, including the next action and its confirmation. Compare what the wording promises with the result that the system produces; a fluent sentence can still describe the wrong operation. Save the observed language, build and state so the fix can be checked again when the application changes.

6. A price label seems to convert currencies

A user switches region and thinks the checkout total has been recalculated. Before closing the issue, test a direct URL and a language switch back to the source edition. Corrections that work only through the home page can leave readers stranded when they arrive from bookmarks, notifications or search results. The visible problem is worth describing exactly before opening a translation file: write down the selected language, the route and the state in which the words appeared. That short account gives a translator and an engineer the same starting point.

Display formatting uses a different currency convention but the stored amount remains unchanged. Show a clear currency code and only perform conversion through a separately defined pricing rule. Avoid changing source data or disabling a validation rule merely to make a sentence look better. The repair should be narrow enough to explain and broad enough to cover the full interaction. If the symptom disappears only on one carefully prepared development screen, the user problem may still exist.

Compare the backend total and displayed currency in each locale. Re-run the relevant path after the correction, including the next action and its confirmation. Compare what the wording promises with the result that the system produces; a fluent sentence can still describe the wrong operation. Save the observed language, build and state so the fix can be checked again when the application changes.

7. The text does not fit a small phone

A translated call-to-action is clipped inside a narrow fixed-width button. Review the public output as if you had never seen the original project. A developer may recognize the intended behavior from code, but a visitor sees only the wording and the next available action. If the screen needs a private explanation to be understood, improve the screen itself. The visible problem is worth describing exactly before opening a translation file: write down the selected language, the route and the state in which the words appeared. That short account gives a translator and an engineer the same starting point.

The widget assumed English-length copy and lacks flexible constraints or wrapping. Use adaptive layout, meaningful line breaks and text scaling instead of deleting required meaning. Avoid changing source data or disabling a validation rule merely to make a sentence look better. The repair should be narrow enough to explain and broad enough to cover the full interaction. If the symptom disappears only on one carefully prepared development screen, the user problem may still exist.

Test small devices with enlarged accessibility text and the longest supported labels. Re-run the relevant path after the correction, including the next action and its confirmation. Compare what the wording promises with the result that the system produces; a fluent sentence can still describe the wrong operation. Save the observed language, build and state so the fix can be checked again when the application changes.

8. An RTL setting leaves icons pointing the wrong way

Navigation text is right-to-left but a directional chevron still implies the opposite route. The safest translation proof is an observed outcome, not a claim that a file exists. Pair the translated statement with a reproducible action and note which values remain unchanged. Where a fallback appears, explain the choice rather than presenting it as a finished language edition. The visible problem is worth describing exactly before opening a translation file: write down the selected language, the route and the state in which the words appeared. That short account gives a translator and an engineer the same starting point.

A hard-coded direction or icon was not evaluated with Directionality-aware layout. Use direction-aware components and inspect icons that signify motion, previous and next. Avoid changing source data or disabling a validation rule merely to make a sentence look better. The repair should be narrow enough to explain and broad enough to cover the full interaction. If the symptom disappears only on one carefully prepared development screen, the user problem may still exist.

Navigate through the task in an RTL language with assistive technology enabled. Re-run the relevant path after the correction, including the next action and its confirmation. Compare what the wording promises with the result that the system produces; a fluent sentence can still describe the wrong operation. Save the observed language, build and state so the fix can be checked again when the application changes.

9. The user’s selection resets after closing the app

A returning person has to choose French again after every launch. Check the boundary between content and operations. Changing a label must not create a new permission, change a price or silently substitute a different workflow. A linguistic improvement is complete only when the functional promise and the underlying action still match. The visible problem is worth describing exactly before opening a translation file: write down the selected language, the route and the state in which the words appeared. That short account gives a translator and an engineer the same starting point.

The locale was stored only in transient widget state and not in persistent preferences. Persist a supported locale code and apply it before or during root app configuration. Avoid changing source data or disabling a validation rule merely to make a sentence look better. The repair should be narrow enough to explain and broad enough to cover the full interaction. If the symptom disappears only on one carefully prepared development screen, the user problem may still exist.

Force close and reopen the app, then verify both text and device-selected formatting. Re-run the relevant path after the correction, including the next action and its confirmation. Compare what the wording promises with the result that the system produces; a fluent sentence can still describe the wrong operation. Save the observed language, build and state so the fix can be checked again when the application changes.

10. The device locale is unsupported

A device set to a regional variant shows unexpected source-language text. Review both ordinary and uncomfortable paths: a successful request, an invalid entry, an expired session and a denied action. The text that appears only during failure may carry the strongest obligation to be clear. Treat it as first-class content. The visible problem is worth describing exactly before opening a translation file: write down the selected language, the route and the state in which the words appeared. That short account gives a translator and an engineer the same starting point.

Supported locales and resolution policy do not define how neutral and regional variants are handled. Specify supportedLocales and a documented fallback without claiming all variants are fully translated. Avoid changing source data or disabling a validation rule merely to make a sentence look better. The repair should be narrow enough to explain and broad enough to cover the full interaction. If the symptom disappears only on one carefully prepared development screen, the user problem may still exist.

Test a regional device language absent from the ARB set and confirm the actual language shown. Re-run the relevant path after the correction, including the next action and its confirmation. Compare what the wording promises with the result that the system produces; a fluent sentence can still describe the wrong operation. Save the observed language, build and state so the fix can be checked again when the application changes.

11. Localizing framework widgets is forgotten

App labels are translated but material date pickers and default controls remain English. Ask a reader who did not help build the feature to complete the task. Record where they hesitate and what they believe the control will do. That evidence often reveals a problem neither machine translation scores nor unit tests can see. The visible problem is worth describing exactly before opening a translation file: write down the selected language, the route and the state in which the words appeared. That short account gives a translator and an engineer the same starting point.

Only custom ARB messages were connected, not the framework localization delegates. Include required framework delegates and test standard controls rather than assuming they follow app messages. Avoid changing source data or disabling a validation rule merely to make a sentence look better. The repair should be narrow enough to explain and broad enough to cover the full interaction. If the symptom disappears only on one carefully prepared development screen, the user problem may still exist.

Open a date picker, accessibility prompt and standard navigation component in the target locale. Re-run the relevant path after the correction, including the next action and its confirmation. Compare what the wording promises with the result that the system produces; a fluent sentence can still describe the wrong operation. Save the observed language, build and state so the fix can be checked again when the application changes.

12. Text assembled from widgets reads in the wrong order

A sentence made from a label, count and suffix becomes unnatural in another language. Before closing the issue, test a direct URL and a language switch back to the source edition. Corrections that work only through the home page can leave readers stranded when they arrive from bookmarks, notifications or search results. The visible problem is worth describing exactly before opening a translation file: write down the selected language, the route and the state in which the words appeared. That short account gives a translator and an engineer the same starting point.

The sentence was built from fragments rather than one translation unit with a dynamic argument. Move grammar into a complete localized message and pass only the required variable. Avoid changing source data or disabling a validation rule merely to make a sentence look better. The repair should be narrow enough to explain and broad enough to cover the full interaction. If the symptom disappears only on one carefully prepared development screen, the user problem may still exist.

Ask a fluent reader to inspect the entire sentence in a real widget. Re-run the relevant path after the correction, including the next action and its confirmation. Compare what the wording promises with the result that the system produces; a fluent sentence can still describe the wrong operation. Save the observed language, build and state so the fix can be checked again when the application changes.

13. A web build works but the release app does not

A translation appears in a browser preview yet the packaged device app omits it. Review the public output as if you had never seen the original project. A developer may recognize the intended behavior from code, but a visitor sees only the wording and the next available action. If the screen needs a private explanation to be understood, improve the screen itself. The visible problem is worth describing exactly before opening a translation file: write down the selected language, the route and the state in which the words appeared. That short account gives a translator and an engineer the same starting point.

The release artifact has a different dependency, asset or generated-code configuration. Generate and test the exact signed or staged release build rather than relying on hot reload. Avoid changing source data or disabling a validation rule merely to make a sentence look better. The repair should be narrow enough to explain and broad enough to cover the full interaction. If the symptom disappears only on one carefully prepared development screen, the user problem may still exist.

Install on a clean device without a developer cache and inspect an end-to-end localized task. Re-run the relevant path after the correction, including the next action and its confirmation. Compare what the wording promises with the result that the system produces; a fluent sentence can still describe the wrong operation. Save the observed language, build and state so the fix can be checked again when the application changes.

14. A screen reader announces an English icon label

The visual text is translated but the Semantics label remains the source language. The safest translation proof is an observed outcome, not a claim that a file exists. Pair the translated statement with a reproducible action and note which values remain unchanged. Where a fallback appears, explain the choice rather than presenting it as a finished language edition. The visible problem is worth describing exactly before opening a translation file: write down the selected language, the route and the state in which the words appeared. That short account gives a translator and an engineer the same starting point.

The accessibility string was hard-coded separately from the rendered title. Localize semantic labels and preserve the same true action description as the visible control. Avoid changing source data or disabling a validation rule merely to make a sentence look better. The repair should be narrow enough to explain and broad enough to cover the full interaction. If the symptom disappears only on one carefully prepared development screen, the user problem may still exist.

Navigate without sight through the key path in the target language. Re-run the relevant path after the correction, including the next action and its confirmation. Compare what the wording promises with the result that the system produces; a fluent sentence can still describe the wrong operation. Save the observed language, build and state so the fix can be checked again when the application changes.

15. A date changes meaning across midnight

An event time displays a different calendar day after device language changes. Check the boundary between content and operations. Changing a label must not create a new permission, change a price or silently substitute a different workflow. A linguistic improvement is complete only when the functional promise and the underlying action still match. The visible problem is worth describing exactly before opening a translation file: write down the selected language, the route and the state in which the words appeared. That short account gives a translator and an engineer the same starting point.

Time zone handling and locale formatting were combined without defining the event instant. Keep the stored instant stable and format with the intended zone and locale. Avoid changing source data or disabling a validation rule merely to make a sentence look better. The repair should be narrow enough to explain and broad enough to cover the full interaction. If the symptom disappears only on one carefully prepared development screen, the user problem may still exist.

Compare two time zones across a daylight-saving boundary or near midnight. Re-run the relevant path after the correction, including the next action and its confirmation. Compare what the wording promises with the result that the system produces; a fluent sentence can still describe the wrong operation. Save the observed language, build and state so the fix can be checked again when the application changes.

16. A translator modifies JSON structure accidentally

An ARB file looks translated but parsing fails during generation. Review both ordinary and uncomfortable paths: a successful request, an invalid entry, an expired session and a denied action. The text that appears only during failure may carry the strongest obligation to be clear. Treat it as first-class content. The visible problem is worth describing exactly before opening a translation file: write down the selected language, the route and the state in which the words appeared. That short account gives a translator and an engineer the same starting point.

Non-message metadata or braces were edited without respecting JSON and ICU syntax. Validate ARB input, protect placeholders and code-review the structured difference. Avoid changing source data or disabling a validation rule merely to make a sentence look better. The repair should be narrow enough to explain and broad enough to cover the full interaction. If the symptom disappears only on one carefully prepared development screen, the user problem may still exist.

Run gen_l10n on a fresh build and test the specific changed message. Re-run the relevant path after the correction, including the next action and its confirmation. Compare what the wording promises with the result that the system produces; a fluent sentence can still describe the wrong operation. Save the observed language, build and state so the fix can be checked again when the application changes.

17. One screen mixes device language and app language

Settings use Spanish while a server-driven offer appears only in English. Ask a reader who did not help build the feature to complete the task. Record where they hesitate and what they believe the control will do. That evidence often reveals a problem neither machine translation scores nor unit tests can see. The visible problem is worth describing exactly before opening a translation file: write down the selected language, the route and the state in which the words appeared. That short account gives a translator and an engineer the same starting point.

Local resources and remote content services apply different locale priorities. Send a supported locale to remote content services and disclose fallback when no edition exists. Avoid changing source data or disabling a validation rule merely to make a sentence look better. The repair should be narrow enough to explain and broad enough to cover the full interaction. If the symptom disappears only on one carefully prepared development screen, the user problem may still exist.

Capture the app’s chosen locale and the API response language for the same session. Re-run the relevant path after the correction, including the next action and its confirmation. Compare what the wording promises with the result that the system produces; a fluent sentence can still describe the wrong operation. Save the observed language, build and state so the fix can be checked again when the application changes.

18. A translation changes the legal promise

A button says a subscription is canceled immediately but the backend only schedules expiration. Before closing the issue, test a direct URL and a language switch back to the source edition. Corrections that work only through the home page can leave readers stranded when they arrive from bookmarks, notifications or search results. The visible problem is worth describing exactly before opening a translation file: write down the selected language, the route and the state in which the words appeared. That short account gives a translator and an engineer the same starting point.

The target wording was optimized for brevity rather than the actual transactional state. Review high-impact messages with the product owner and keep states such as pending and completed distinct. Avoid changing source data or disabling a validation rule merely to make a sentence look better. The repair should be narrow enough to explain and broad enough to cover the full interaction. If the symptom disappears only on one carefully prepared development screen, the user problem may still exist.

Perform the transaction in a test account and compare the resulting status to the wording. Re-run the relevant path after the correction, including the next action and its confirmation. Compare what the wording promises with the result that the system produces; a fluent sentence can still describe the wrong operation. Save the observed language, build and state so the fix can be checked again when the application changes.

A practical seven-stage release plan

1. Define one real audience and its tasks

Select a real task with a beginning, a decision and a final outcome. Include a first-time visitor and a returning account holder. The target language should be chosen because people need it, not because a dropdown can technically display it. Identify high-risk passages such as permissions, charges, deadlines and destructive actions. Write acceptance criteria in ordinary language and include the actual screen or response that proves them.

For Flutter gen_l10n and ARB localization, specifically relate this stage to Set the Flutter generate flag, configure l10n.yaml where needed, and treat the template ARB as the source message inventory that language editions must track. A passing release note should name the tested language, a representative reader task and what the screen actually did. If the result cannot be described without relying on a private developer setup, extend the test to the deployed experience. This prevents a catalog that looks complete in a repository from becoming an incomplete product for readers.

2. Inventory messages and hidden surfaces

Inventory visible text, hidden validation messages, generated notices, notifications, navigation, search descriptions and accessibility names. Look for fragments assembled from multiple strings and for copied source-language text outside the translation system. An inventory without ownership goes stale quickly: assign each message family to a feature and keep the translation update associated with the corresponding software change.

For Flutter gen_l10n and ARB localization, specifically relate this stage to Use plural messages as complete grammatical units, not as concatenated singular suffixes. ICU-style placeholders must preserve correct argument references and format. A passing release note should name the tested language, a representative reader task and what the screen actually did. If the result cannot be described without relying on a private developer setup, extend the test to the deployed experience. This prevents a catalog that looks complete in a repository from becoming an incomplete product for readers.

3. Agree on language and fallback rules

Define how the application chooses a language on first visit and after a user changes it. Distinguish the content language from regional formatting and the user’s time zone. Specify precedence between a saved setting, an explicit switch, a route or a browser request. Identify what happens if a requested locale is unsupported. Write that policy before debugging a surprising page; otherwise developers may each make an inconsistent local decision.

For Flutter gen_l10n and ARB localization, specifically relate this stage to MaterialApp or the relevant app shell needs supported locales and delegates so both app strings and framework components can render in the chosen language. A passing release note should name the tested language, a representative reader task and what the screen actually did. If the result cannot be described without relying on a private developer setup, extend the test to the deployed experience. This prevents a catalog that looks complete in a repository from becoming an incomplete product for readers.

4. Build a representative language edition

Begin with one complete path rather than a broad selection of isolated translated labels. Translate the instructions, action controls, error states, final confirmation and a help route. Include representative short and long wording. Populate test values that expose different plural categories, negative numbers, decimal separators and long names, but do not alter the business meaning or state machine to make the page easier to translate.

For Flutter gen_l10n and ARB localization, specifically relate this stage to The language of a message and the region of a numeric format are related but not identical decisions. A currency symbol, amount and exchange rate have different meanings. A passing release note should name the tested language, a representative reader task and what the screen actually did. If the result cannot be described without relying on a private developer setup, extend the test to the deployed experience. This prevents a catalog that looks complete in a repository from becoming an incomplete product for readers.

5. Review meaning and interaction together

Run two reviews with different goals. A fluent reviewer decides whether the text is natural, unambiguous and appropriate to the audience. A domain or product reviewer decides whether the statement corresponds to what the system actually does. When they disagree, reproduce the behavior and revise the source if necessary. Translation should not be used to hide an unresolved defect in the source instructions.

For Flutter gen_l10n and ARB localization, specifically relate this stage to Generated localizations belong to a build and packaging process. Clean release testing should reveal missing artifacts, missing font glyphs and unsupported device variants. A passing release note should name the tested language, a representative reader task and what the screen actually did. If the result cannot be described without relying on a private developer setup, extend the test to the deployed experience. This prevents a catalog that looks complete in a repository from becoming an incomplete product for readers.

6. Exercise a controlled pre-release matrix

Prepare fresh-session and signed-in tests, direct links, browser preference conflicts, missing entries, unsupported variants, network errors and keyboard use. Compare rendered output with stored data. Capture the deployed route, the build, the language chosen, the specific action taken and the observed result. A passing checklist that does not include real interaction is weaker evidence than one end-to-end recording of a critical task.

7. Ship, monitor, and correct

Release a small set of supported languages with clear support boundaries. Monitor missing-resource warnings, mistaken route redirects, confusing validation language and support requests. Corrections should be versioned and rechecked in every affected language. Give teams a simple way to escalate a mistranslated condition and to roll back a bad translation without destroying otherwise correct work.

A multilingual acceptance checklist

An explicit language selection leads to the intended edition and survives the expected return visit.
Every required field and error explains the real validation rule without reversing conditions.
Counts, variables, names and values display correctly at meaningful boundaries.
Dates, currencies and units are formatted without changing stored facts or making unauthorized conversions.
Accessible names, help routes, dialogs and confirmations are usable in the selected language.
Unsupported language variants and missing messages follow a truthful, documented fallback.
Direct links, refreshes, authenticated transitions and deployed builds have been exercised.
A reviewer can reproduce each serious problem using locale, state, route and build evidence.

Use this checklist as a set of observations, not as a marketing claim. For example, "100 percent translated" may mean every message has a nonempty resource value, while a reader is still unable to find the correct help link. Acceptance should therefore include the route that was tested, the device or browser where appropriate and the outcome of the action. It is better to support fewer languages well than to declare complete coverage prematurely.

Frequently asked questions

What is an ARB file in Flutter?

It is a structured message resource, typically JSON-formatted, carrying localized text and optional metadata for code generation.

In practice, test the answer with an installed release of Flutter gen_l10n and ARB localization, an actual reader-facing message and a meaningful action. The documentation explains what the technology offers; a real test establishes what this particular application has implemented.

Does gen_l10n write the translation?

No. It generates Dart localization accessors from supplied resources; meaning still requires human review.

Why is my AppLocalizations import different?

Output locations depend on the Flutter version and l10n.yaml options; follow the current installed tool guidance.

Do supportedLocales automatically translate every widget?

No. They describe supported locales, while delegates and translated message resources supply the actual wording.

Can locale switching change a purchase price?

Not by itself. Formatting is distinct from conversion and the application’s pricing rules.

Are RTL languages only a text issue?

No. Layout, directional icons, focus order and accessible navigation must also be checked.

What should be tested on physical devices?

Cold start, persistence, dialogs, system controls, long labels, fonts and the packaged release artifact.

Where is the official current setup?

The Flutter internationalization documentation includes gen_l10n, ARB conventions and configuration options.

Official documentation and further reading

The platform behavior described here should be checked against the exact installed version. Start with its primary documentation and review release notes whenever a tool, runtime or framework is upgraded. Official references are useful for technical contracts; translation decisions still need a competent review of the meaning readers receive.

For the broader relationship between language, culture, context and intended meaning, see Master Art of Translation: The Complete System. Browse the Translate Like a Pro series index for other platform-specific guides. This article concentrates on Flutter gen_l10n and ARB localization implementation so it does not replace guides to general translation theory, human revision or unrelated products.

A useful multilingual release leaves the reader with a correct understanding and a working next step. Maintain that condition after source changes, policy revisions, new locales and framework updates. A reliable translation is part of the product’s operational truth, not a decorative layer of words.

Translate Like a Pro | 6740 — Flutter gen_l10n ARB Files, AppLocalizations, Plurals, Locale Switching and App QA