This directory contains scripts for generating Dart localizations. Currently it is only used by material_ui and cupertino_ui.
For details that are specific to the localizations of material_ui, see packages/material_ui/lib/src/l10n/README.md.
The Widgets library generates its localizations in a similar fashion to these scripts, located in flutter/flutter at dev/tools/localization.
The Material and Cupertino libraries use Application Resource Bundle files, which have a .arb extension, to store localized translations of messages, format strings, and other values. This format is also used by the Dart intl package.
The Material and Cupertino libraries only depend on a small subset of the ARB format. Each .arb file contains a single JSON table that maps from resource IDs to localized values.
Filenames contain the locale that the values have been translated for. For example material_de.arb contains German translations, and material_ar.arb contains Arabic translations. Files that contain regional translations have names that include the locale's regional suffix. For example material_en_GB.arb contains additional English translations that are specific to Great Britain.
There is one language-specific .arb file for each supported locale. If an additional file with a regional suffix is present, the regional localizations are automatically merged with the language-specific ones.
The JSON table's keys, called resource IDs, are valid Dart variable names. They correspond to methods from the MaterialLocalizations or CupertinoLocalizations class. For example:
Material:
Widget build(BuildContext context) { return TextButton( child: Text( MaterialLocalizations.of(context).cancelButtonLabel, ), ); }
Cupertino:
Widget build(BuildContext context) { return CupertinoButton( child: Text( CupertinoLocalizations.of(context).cancelButtonLabel, ), ); }
Each of these widget build methods creates a button whose label is the local translation of “Cancel” which is defined for the cancelButtonLabel resource ID.
Each of the language-specific .arb files contains an entry for cancelButtonLabel.
All of the material_*.arb and cupertino_*.arb files whose names do not include a regional suffix contain translations for the same set of resource IDs as material_en.arb and cupertino_en.arb, respectively.
For each resource ID defined for English, there is an additional resource with an ‘@’ prefix. These ‘@’ resources are not used by the generated Dart code at run time, they just exist to inform translators about how the value will be used, and to inform the code generator about what code to write.
"cancelButtonLabel": "Cancel", "@cancelButtonLabel": { "description": "The label for cancel buttons and menu items." },
A few of the Material and Cupertino translations contain $variable tokens. The Material and Cupertino libraries replace these tokens with values at run-time. For example:
Material:
"aboutListTileTitle": "About $applicationName",
Cupertino:
"datePickerHourSemanticsLabelOne": "$hour o'clock",
The value for this resource ID is retrieved with a parameterized method instead of a simple getter:
Material:
MaterialLocalizations.of(context).aboutListTileTitle(yourAppTitle)
Cupertino:
CupertinoLocalizations.of(context).datePickerHourSemanticsLabel(hour)
The names of the $variable tokens must match the names of the MaterialLocalizations or CupertinoLocalizations method parameters.
Plurals are handled similarly, with a lookup method that includes a quantity parameter. For example:
Material: selectedRowCountTitle returns a string like “1 item selected” or “no items selected”.
MaterialLocalizations.of(context).selectedRowCountTitle(yourRowCount)
Cupertino: datePickerMinuteSemanticsLabel returns a string like “1 minute” or “2 minutes”.
CupertinoLocalizations.of(context).datePickerMinuteSemanticsLabel(minute)
Plural translations can be provided for several quantities: 0, 1, 2, “few”, “many”, “other”. The variations are identified by a resource ID suffix which must be one of “Zero”, “One”, “Two”, “Few”, “Many”, “Other”. The “Other” variation is used when none of the other quantities apply. All plural resources must include a resource with the “Other” suffix. For example:
Material: the English translations (material_en.arb) for selectedRowCountTitle are:
"selectedRowCountTitleZero": "No items selected", "selectedRowCountTitleOne": "1 item selected", "selectedRowCountTitleOther": "$selectedRowCount items selected",
Cupertino: the English translations (cupertino_en.arb) for datePickerMinuteSemanticsLabel are:
"datePickerMinuteSemanticsLabelOne": "1 minute", "datePickerMinuteSemanticsLabelOther": "$minute minutes",
When defining new resources that handle pluralizations, the “One” and the “Other” forms must, at minimum, always be defined in the source English ARB files.
If you (someone contributing to the package) want to add a new string to the MaterialLocalizations or CupertinoLocalizations object (e.g. because you've added a new widget and it has a tooltip), follow these steps:
String get showMenuTooltip;
to the localizations class MaterialLocalizations, in packages/material_ui/lib/src/material_localizations.dart, or CupertinoLocalizations, in packages/cupertino_ui/lib/src/localizations.dart;
String aboutListTileTitle(String applicationName);
to the same localization class.
Implement a default return value in DefaultMaterialLocalizations or DefaultCupertinoLocalizations in the same file as in step 1.
@override String get showMenuTooltip => 'Show menu';
@override String aboutListTileTitle(String applicationName) => 'About $applicationName';
For messages with parameters, do also add the function to GlobalMaterialLocalizations in packages/material_ui/lib/src/global_material_localizations.dart or GlobalCupertinoLocalizations in packages/cupertino_ui/lib/src/global_cupertino_localizations.dart, and add a raw getter as demonstrated below:
/// The raw version of [aboutListTileTitle], with `$applicationName` verbatim
/// in the string.
@protected
String get aboutListTileTitleRaw;
@override
String aboutListTileTitle(String applicationName) {
final String text = aboutListTileTitleRaw;
return text.replaceFirst(r'$applicationName', applicationName);
}
Add a test to the package's test/localizations_test.dart that verifies that this new value is implemented.
Update the .arb files. To add a new string to the .arb files, you must first add it to the English translations (packages/material_ui/lib/src/l10n/material_en.arb or packages/cupertino_ui/lib/src/l10n/cupertino_en.arb), including a description.
"showMenuTooltip": "Show menu",
"@showMenuTooltip": {
"description": "The tooltip for the button that shows a popup menu."
},
"aboutListTileTitle": "About $applicationName",
"@aboutListTileTitle": {
"description": "The default title for the drawer item that shows an about page for the application. The value of $applicationName is the name of the application, like GMail or Chrome.",
"parameters": "applicationName"
},
Then you need to add new entries for the string to all of the other language locale files by running the following from the repo root:
dart script/l10n/bin/gen_missing_localizations.dart
Which will copy the English strings into the other locales as placeholders until they can be translated.
Finally you need to re-generate packages/material_ui/lib/src/l10n/generated_material_localizations.dart and packages/cupertino_ui/lib/src/l10n/generated_cupertino_localizations.dart by running the following from the repo root:
dart script/l10n/bin/gen_localizations.dart --overwrite
If you got an error when running this command, this issue might be helpful.
TL;DR: If you got the same type of errors as discussed in the issue, run this instead from the repo root:
dart script/l10n/bin/gen_localizations.dart --overwrite --remove-undefined
If you are a Google employee, you should then also follow the instructions at go/flutter-l10n. If you‘re not, don’t worry about it.
If you (someone contributing to the package) want to modify an existing string in the MaterialLocalizations or CupertinoLocalizations objects, follow these steps:
Modify the default value of the relevant getter(s) in DefaultMaterialLocalizations or DefaultCupertinoLocalizations.
Update the .arb files. Modify the out-of-date English strings in packages/material_ui/lib/src/l10n/material_en.arb or packages/cupertino_ui/lib/src/l10n/cupertino_en.arb.
You also need to re-generate packages/material_ui/lib/src/l10n/generated_material_localizations.dart and packages/cupertino_ui/lib/src/l10n/generated_cupertino_localizations.dart by running the following from the repo root:
dart script/l10n/bin/gen_localizations.dart --overwrite
This script may result in your updated getters being created in newer locales and set to the old value of the strings. This is to be expected. Leave them as they were generated, and they will be picked up for translation.
If you are a Google employee, you should then also follow the instructions at go/flutter-l10n. If you‘re not, don’t worry about it.
The gen_missing_localizations script is used to quickly add placeholder values to all locale files when adding a new localization string. Add the new localization string to the English .arb file and run this script, and all other language locale .arb files (those without a regional suffix) will be updated with the new string.
All of the localizations are combined in a single file per library (generated_material_localizations.dart and generated_cupertino_localizations.dart) using the gen_localizations script.
You can see what that script would generate by running the following from the repo root:
dart script/l10n/bin/gen_localizations.dart
Actually update the generated files with the following run from the repo root:
dart script/l10n/bin/gen_localizations.dart --overwrite
The gen_localizations script just combines the contents of all of the .arb files, each into a class which extends GlobalMaterialLocalizations or GlobalCupertinoLocalizations. The MaterialLocalizations and CupertinoLocalizations class implementations use these to lookup localized resource values.
The gen_localizations script must be run by hand after .arb files have been updated.
Originally, the material_kn.arb and cupertino_kn.arb files contained unicode characters that can cause current versions of Emacs on Linux to crash. There is more information here: https://github.com/flutter/flutter/issues/36704.
Rather than risking developers' editor sessions, the strings in these arb files (and the code generated for them) have been encoded using the appropriate escapes for JSON and Dart. The JSON format arb files are rewritten by script/l10n/bin/encode_kn_arb_files.dart, which gen_localizations runs when --overwrite is passed. The localizations code generator uses generateEncodedString() from script/l10n/lib/localizations_utils.dart.
The translations (the .arb files) in packages/material_ui/lib/src/l10n and packages/cupertino_ui/lib/src/l10n are based on the English translations in material_en.arb and cupertino_en.arb. Google contributes translations for all the languages supported by these packages. (Googlers, for more details see <go/flutter-l10n>.)
If you have feedback about the translations please file an issue on the Flutter github repo.
The Internationalizing Flutter Apps tutorial describes how to use the internationalization APIs in an ordinary Flutter app.
Application Resource Bundle covers the .arb file format used to store localized translations of messages, format strings, and other values.
The Dart intl package supports internationalization.
The flutter_localizations package, which contains the localizations for the core framework and is where these Material and Cupertino localizations were originally located.