Flutter Localization and Internationalization

Soluling home Document home

Flutter (Wikipedia) is a popular UI software development kit for building mobile, web, and desktop applications from a single Dart code base. Flutter stores the strings of an application in ARB (Application Resource Bundle) files. Soluling Desktop and Soluling Cloud support Flutter ARB files.

Add localization to your Flutter application
ARB file format
Escaping
Localization process
Samples
Configuring Flutter localization

Add localization to your Flutter application

Flutter's gen-l10n tool generates Dart code from the ARB files. Add the localization packages to pubspec.yaml and turn on code generation.

dependencies:
  flutter:
    sdk: flutter
  flutter_localizations:
    sdk: flutter
  intl: any

flutter:
  generate: true

Then add l10n.yaml to the root of the project. It tells gen-l10n where the ARB files are and which file is the original (template) file.

arb-dir: lib/l10n
template-arb-file: app_en.arb

Write the original strings into lib/l10n/app_en.arb and add the generated localizations delegates and supported locales to your MaterialApp.

import 'package:flutter_gen/gen_l10n/app_localizations.dart';
...
MaterialApp(
  localizationsDelegates: AppLocalizations.localizationsDelegates,
  supportedLocales: AppLocalizations.supportedLocales,
  ...
)

Finally, replace the hard coded strings of your widgets with the generated getters.

Text(AppLocalizations.of(context)!.helloWorld)

When you run flutter run or flutter gen-l10n, Flutter generates the AppLocalizations class from the ARB files. Each localized ARB file (e.g., app_fi.arb) adds a supported language. The import path of the generated class depends on your Flutter version and l10n.yaml settings.

ARB file format

An ARB file is a JSON file. Each string has a key and a value. A key that starts with @ contains metadata of the string with the same name. The following is a part of app_en.arb of the Simple sample.

{
  "helloWorld": "Hello World!",
  "@helloWorld": {
    "description": "The conventional newborn programmer greeting"
  },
  "hello": "Hello {userName}",
  "@hello": {
    "description": "A message with a single parameter",
    "placeholders": {
      "userName": {
        "type": "String",
        "example": "Bob"
      }
    }
  },
  "nWombats": "{count, plural, one {{count} wombat} other {{count} wombats}}",
  "pronoun": "{gender, select, male{he} female{she} other{they}}"
}

Soluling reads the file as follows:

Item	Description
Strings	Each key whose name does not start with `@` becomes a row. The key is the context of the row.
Description	The `description` of the metadata becomes the comment that the translator sees. Write descriptions especially for strings that contain placeholders.
Placeholders	Placeholders, such as `{userName}`, must be kept in the translation. Their order can change if the target language needs it.
Plurals and selects	ICU plural and select patterns, such as `nWombats` and `pronoun`, let the translator enter the right number of plural forms and the values of the select cases for each language.

When building, Soluling writes a localized ARB file for each language. The localized file contains the translated strings, and its name contains the language code, for example, app_fi.arb for Finnish.

Escaping

If you set use-escaping: true in l10n.yaml, single quotes are escape characters in the ARB files: text between single quotes, such as '{Isn''t}', is literal text, and two single quotes ('') mean one single quote.

{
  "helloWorld": "Hello! '{Isn''t}' this a wonderful day?",
  "sample": "One''Two"
}

Soluling handles this with the File uses escaping option on the Options sheet. When it is checked, Soluling shows the translator the unescaped text (e.g., One'Two) and escapes the translations when it writes the localized files. See the Escape sample.

Note! File uses escaping is checked by default, but Flutter's use-escaping is off by default. If your l10n.yaml does not set use-escaping: true, uncheck the option. Otherwise, a string such as Don't is read incorrectly.

Localization process

You can localize ARB files in Soluling Desktop, and you can use Soluling Cloud for translating.

Desktop process

Start Soluling. Drag the original ARB file (e.g., lib/l10n/app_en.arb) on Soluling or click the New from File or Files button and select the file.
Project Wizard appears. If your l10n.yaml does not set use-escaping: true, uncheck File uses escaping (see Escaping). Select English as the original language and the target languages, for example, Finnish and Spanish, and complete the wizard.
Translate the project.
Choose Home | Build All to build the localized ARB files. Soluling creates them into the same directory as the original file, for example, lib/l10n/app_fi.arb.
Run flutter gen-l10n (or just build your application) so that Flutter generates the code for the new languages.

When you change the strings in the original ARB file, open the Soluling project and choose Home | Scan. Soluling keeps the existing translations, and you only translate the strings that were added or changed.

Cloud process

With Soluling Cloud, you and your translators can translate the strings in a browser using Translate. Create the project in Soluling Desktop first, upload it to Soluling Cloud, and build the localized ARB files in Soluling Desktop. You need a Soluling account. See the available Cloud plans.

Upload the project

Create the project in Soluling Desktop as described in Desktop process, and save it. This creates the Soluling project file (.ntp).
On the Translate tab, in the Send and Receive group, click Configure Cloud.
Log in with your Soluling account, and select the cloud account to use if you have several.
Click OK to create the cloud project. When Soluling asks whether to upload the local project to the cloud, click Yes, and Yes again to wait until the cloud has processed it.

The project now also appears on the dashboard (Cloud > Dashboard for Projects, Users and Terminology at www.soluling.com).

Translate the project

Click the project's green Translate button on the dashboard and translate, or click the project's Manage button and invite a translator for each language under Languages and Invitations.

Get the translations back

In Soluling Desktop, on the Translate tab, click Import from Cloud. Soluling downloads the translations made in the cloud and imports them into your local project. Then choose Home | Build All to build the localized ARB files.

Update the project

When you change the strings, in Soluling Desktop, on the Home tab, click Scan so the project picks up the changes. On the Translate tab, click Upload to Cloud. Translate the new and changed strings in Translate, then Import from Cloud and build again. To do the same steps from a build script, use SoluMake. See the Cloud tutorial.

Samples

GitHub and <data-dir>\Samples\Flutter contain the following Flutter samples:

Directory	Description	Notes
Simple	The original ARB file (app_en.arb) that contains a plain string, a placeholder, a plural, and a select message, and the localized Spanish (app_es.arb) and Finnish (app_fi.arb) files.	Study this first.
Escape	An ARB file that uses escaping (sample.arb) and the localized Finnish file (sample_fi.arb). The project uses the default setting, File uses escaping checked. In the Simple project, the option is unchecked.

The samples contain the ARB files and the Soluling projects, but not a Flutter application. Copy the ARB files into the lib/l10n directory of your application to try them.

Configuring Flutter localization

You create a resource file localization project by adding a Flutter resource file (e.g., lib\l10n\app_en.arb) into your Soluling project. You can configure how to localize your Flutter resource file by selecting the item in the project tree, right-clicking, and choosing the Options menu. A source dialog appears that lets you edit the options. This source uses the following option sheets.