Flutter Localization: ARB Files, gen-l10n and Best Practices

Flutter makes it easy to ship one codebase to iOS, Android, web and desktop. Shipping that app in ten languages is a different story. Flutter has a solid built-in localization system based on ARB files, and once it is set up correctly, adding a new language becomes a translation task rather than a development task. This guide covers the full setup and the workflow that keeps translations flowing.

How Flutter Localization Works

Flutter uses the flutter_localizations package and the intl package, together with a code generator called gen-l10n. You write your strings in ARB files, one per language. The generator turns them into a Dart class with a getter or method for every string, so your code stays type-safe. The official Flutter internationalization guide documents every option.

What Is an ARB File?

ARB (Application Resource Bundle) is a JSON-based format. Each file holds key-value pairs for one locale, for example app_en.arb and app_de.arb. Keys can have metadata entries that start with @, which describe the string and its placeholders for translators.

• "checkoutButton": "Pay now" is a simple string.
• "@checkoutButton": {"description": "Button on the payment screen"} gives translators context.
• Placeholders such as {name} are declared in metadata with their type.
• Plurals and selects use ICU message syntax, for example {count, plural, =0{No items} =1{1 item} other{{count} items}}.

Setting Up Flutter Localization Step by Step

1. Add dependencies. Include flutter_localizations from the SDK and the intl package in pubspec.yaml, and enable code generation.
2. Create l10n.yaml. Point it to your ARB folder, the template file (usually English) and the output file name.
3. Write the template ARB. Add all source strings with descriptions and placeholder metadata.
4. Generate code. Run the generator, which creates the localizations class.
5. Register delegates. Add the generated delegates and supported locales to MaterialApp or CupertinoApp.
6. Use strings in widgets. Replace hard-coded text with calls to the generated class, for example AppLocalizations.of(context)!.checkoutButton.

Best Practices for ARB Files

• Always add descriptions. A short note about where a string appears prevents most translation errors.
• Use ICU plurals and selects instead of building sentences in Dart code.
• Keep keys descriptive, such as profileSaveButton, not button3.
• Never concatenate strings. Word order changes between languages.
• Design for text expansion. German and Finnish strings can be much longer than English.
• Support right-to-left languages by testing Arabic or Hebrew layouts early.

Translating ARB Files

Because ARB is JSON, it can be translated with the same workflow as other JSON locale files. The key rules: never translate keys or metadata, keep placeholders exactly as they are, and complete every plural branch required by the target language. Our guide on how to translate a JSON file without breaking your keys covers the details.

For a growing app, translations should follow the code automatically. Connect your repository to a TMS, pre-translate new strings with translation memory and AI, send them to reviewers and push approved files back. That is the core of continuous localization.

Don't Forget the Store Listings

A Flutter app usually ships to both the App Store and Google Play. Translate titles, descriptions and screenshots for each market, and research local keywords. Our guides to app localization and iOS localization cover the store side.

Common Flutter Localization Mistakes

• Strings left hard-coded in widgets, especially in dialogs and snackbars.
• Placeholders changed or translated by mistake.
• Missing plural branches for languages such as Polish or Arabic.
• Locales added to ARB files but not to the supported locales list.
• Translations edited directly in the repository, then overwritten by the next sync.

How WordBeam Helps Flutter Teams

WordBeam handles JSON locale files with keys and placeholders protected. Because ARB is JSON underneath, teams can export or rename ARB files as JSON and translate them safely in the CAT editor with translation memory, glossary and AI pre-translation. On the Studio plan, GitHub and GitLab integrations keep translations in sync with your code. See how WordBeam supports software localization and UI translations.

Frequently Asked Questions

What is the difference between ARB and JSON?

ARB is based on JSON but adds conventions for metadata, placeholders and ICU messages, which makes it better suited for localization.

Do I need the intl package for Flutter localization?

Yes. It provides message formatting, plurals and locale-aware formatting for dates and numbers.

How do I add a new language to a Flutter app?

Add a new ARB file for the locale, translate it, regenerate the localizations class and include the locale in your supported locales.