README.md 9.42 KB
Newer Older
1
# Material and Cupertino Libraries Localizations
2 3

The `.arb` files in this directory contain localized values (primarily
4 5 6 7 8
strings) used by the Material and Cupertino libraries.  The
`generated_material_localizations.dart` and
`generated_cupertino_localizations.dart` files combine all of the
localizations into a single Map that is linked with the rest of
flutter_localizations package.
9 10

If you're looking for information about internationalizing Flutter
11
apps in general, see the
12
[Internationalizing Flutter Apps](https://flutter.dev/tutorials/internationalization/) tutorial.
13 14 15 16


### Translations for one locale: .arb files

17
The Material and Cupertino libraries use
18 19 20
[Application Resource Bundle](https://code.google.com/p/arb/wiki/ApplicationResourceBundleSpecification)
files, which have a `.arb` extension, to store localized translations
of messages, format strings, and other values. This format is also
21
used by the Dart [intl](https://pub.dev/packages/intl)
22 23 24
package and it is supported by the
[Google Translators Toolkit](https://translate.google.com/toolkit).

25 26 27
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.
28 29 30 31 32 33 34 35

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.

Josh Soref's avatar
Josh Soref committed
36
There is one language-specific .arb file for each supported locale. If
37 38 39 40
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
41 42
names. They correspond to methods from the `MaterialLocalizations` or
`CupertinoLocalizations` classes. For example:
43 44 45

```dart
Widget build(BuildContext context) {
46 47
  return FlatButton(
    child: Text(
48 49 50 51 52 53 54 55 56 57 58
      MaterialLocalizations.of(context).cancelButtonLabel,
    ),
  );
}
```

This widget build method 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
59
`cancelButtonLabel`. They're all represented by the `Map` in the
60 61 62 63
generated `localizations.dart` file. The Map is used by the
MaterialLocalizations class.


64
### material_en.arb and cupertino_en.arb Define all of the resource IDs
65

66 67
All of the `material_*.arb` files whose names do not include a regional
suffix contain translations for the same set of resource IDs as
68 69
`material_en.arb`.

70 71 72 73 74 75 76 77 78
Similarly all of the `cupertino_*.arb` files whose names do not include
a regional suffix contain translations for the same set of resource IDs
as `cupertino_en.arb`.

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.
79 80 81 82 83 84 85 86 87 88 89 90 91

```dart
"cancelButtonLabel": "CANCEL",
"@cancelButtonLabel": {
  "description": "The label for cancel buttons and menu items.",
  "type": "text"
},
```


### Values with Parameters, Plurals

A few of material translations contain `$variable` tokens. The
92 93
Material and Cupertino libraries replace these tokens with values at
run-time. For example:
94 95 96 97 98 99 100 101 102 103 104 105

```dart
"aboutListTileTitle": "About $applicationName",
```

The value for this resource ID is retrieved with a parameterized
method instead of a simple getter:

```dart
MaterialLocalizations.of(context).aboutListTileTitle(yourAppTitle)
```

106
The names of the `$variable` tokens must match the names of the
107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131
`MaterialLocalizations` method parameters.


Plurals are handled similarly, with a lookup method that includes a
quantity parameter. For example `selectedRowCountTitle` returns a
string like "1 item selected" or "no items selected".

```dart
MaterialLocalizations.of(context).selectedRowCountTitle(yourRowCount)
```

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 the English translations
('material_en.arb') for `selectedRowCountTitle` are:

```dart
"selectedRowCountTitleZero": "No items selected",
"selectedRowCountTitleOne": "1 item selected",
"selectedRowCountTitleOther": "$selectedRowCount items selected",
```

132 133 134
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.
135

136
### scriptCategory and timeOfDayFormat for Material library
137

138 139 140
In `material_en.arb`, the values of these resource IDs are not
translations, they're keywords that help define an app's text theme
and time picker layout respectively.
141 142 143

The value of `timeOfDayFormat` defines how a time picker displayed by
[showTimePicker()](https://docs.flutter.io/flutter/material/showTimePicker.html)
144 145 146 147 148
formats and lays out its time controls. The value of `timeOfDayFormat`
must be a string that matches one of the formats defined by
<https://docs.flutter.io/flutter/material/TimeOfDayFormat-class.html>.
It is converted to an enum value because the `material_en.arb` file
has this value labeled as `"x-flutter-type": "icuShortTimePattern"`.
149 150

The value of `scriptCategory` is based on the
151
[Language categories reference](https://material.io/design/typography/language-support.html#language-categories-reference)
152 153 154 155
section in the Material spec. The Material theme uses the
`scriptCategory` value to lookup a localized version of the default
`TextTheme`, see
[Typography.geometryThemeFor](https://docs.flutter.io/flutter/material/Typography/geometryThemeFor.html).
156 157


158
### 'generated_*_localizations.dart': all of the localizations as a Map
159

160 161 162 163
If you look at the comment at the top of the `generated_material_localizations.dart`
and `generated_cupertino_localizations.dart` files, you'll
see that it was manually generated using a `dev/tools/localizations`
app called `gen_localizations`.
164 165

You can see what that script would generate by running this command:
166 167

```dart
168
dart dev/tools/localizations/bin/gen_localizations.dart packages/flutter_localizations/lib/src/l10n material
169 170 171
```

The gen_localizations app just combines the contents of all of the
172 173 174
.arb files into a single `Map` per library that has entries for each .arb
file's locale. The `MaterialLocalizations` and `CupertinoLocalizations`
class implementations use these Maps to implement the methods that lookup localized resource values.
175 176 177 178 179 180

The gen_localizations app must be run by hand after .arb files have
been updated. The app's first parameter is the path to this directory,
the second is the file name prefix (the file name less the locale
suffix) for the .arb files in this directory.

181
To in-place update the generated localizations file using the default
182 183 184
values, you can just run:

```dart
185
dart dev/tools/localizations/bin/gen_localizations.dart --overwrite
186 187
```

188

189 190 191 192 193 194 195 196 197
### Special handling for the Kannada (kn) translations

Originally, the cupertino_kn.arb and material_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 were rewritten with
198 199 200
dev/tools/localization/bin/encode_kn_arb_files.dart. The localizations code
generator uses generateEncodedString()
from dev/tools/localization/localizations_utils.dart.
201

202 203 204 205 206 207 208 209 210 211 212 213
### Support for Pashto (ps) translations

When Flutter first set up i18n for the Material library, Pashto (ps)
translations were included for the first set of Material widgets.
However, Pashto was never set up to be continuously maintained in
Flutter by Google, so material_ps.arb was never updated beyond the
initial commit.

To prevent breaking applications that rely on these original Pashto
translations, they will be kept. However, all new strings will have
the English translation until support for Pashto is provided.
See https://github.com/flutter/flutter/issues/60598.
214

215 216
### Translations Status, Reporting Errors

217
The translations (the `.arb` files) in this directory are based on the
218 219 220
English translations in `material_en.arb` and `cupertino_en.arb`.
Google contributes translations for all the languages supported by
this package. (Googlers, for more details see <go/flutter-l10n>.)
221 222

If you have feedback about the translations please
223
[file an issue on the Flutter github repo](https://github.com/flutter/flutter/issues/new?template=BUG.md).
224 225 226 227


### See Also

228
The [Internationalizing Flutter Apps](https://flutter.dev/tutorials/internationalization/)
Josh Soref's avatar
Josh Soref committed
229
tutorial describes how to use the internationalization APIs in an
230 231 232 233 234 235
ordinary Flutter app.

[Application Resource Bundle](https://code.google.com/p/arb/wiki/ApplicationResourceBundleSpecification)
covers the `.arb` file format used to store localized translations
of messages, format strings, and other values.

236
The Dart [intl](https://pub.dev/packages/intl)
237
package supports internationalization.