README.md 6.8 KB
Newer Older
1
# Material Library Localizations
2 3 4

The `.arb` files in this directory contain localized values (primarily
strings) used by the material library.  The `localizations.dart` file
5 6
combines all of the localizations into a single Map that is
linked with the rest of flutter_localizations package.
7 8

If you're looking for information about internationalizing Flutter
9
apps in general, see the
10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56
[Internationalizing Flutter Apps](https://flutter.io/tutorials/internationalization/) tutorial.


### Translations for one locale: .arb files

The Material library uses
[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
used by the Dart [intl](https://pub.dartlang.org/packages/intl)
package and it is supported by the
[Google Translators Toolkit](https://translate.google.com/toolkit).

The material library only depends 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-specifc .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`
class. For example:

```dart
Widget build(BuildContext context) {
  return new FlatButton(
    child: new Text(
      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
57
`cancelButtonLabel`. They're all represented by the `Map` in the
58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125
generated `localizations.dart` file. The Map is used by the
MaterialLocalizations class.


### material_en.arb Defines all of the resource IDs

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

For each resource ID defined for English in material_en.arb, there is
an additional resource with an '@' prefix. These '@' resources are not
used by the material library at run time, they just exist to inform
translators about how the value will be used.

```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
material library replaces these tokens with values at run-time. For
example:

```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)
```

The names of the `$variable` tokens match the names of the
`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",
```


126
### Generated file localizations.dart: all of the localizations as a Map
127 128 129

If you look at the comment at the top of `localizations.dart` you'll
see that it was manually generated using a `dev/tools` app called
130 131 132
`gen_localizations`.

You can see what that script would generate by running this command:
133 134

```dart
135
dart dev/tools/gen_localizations.dart packages/flutter_localizations/lib/src/l10n material
136 137 138
```

The gen_localizations app just combines the contents of all of the
139
.arb files into a single `Map` that has entries for each .arb
140 141 142 143 144 145 146 147 148
file's locale. The `MaterialLocalizations` class implementation uses
this Map to implement the methods that lookup localized resource
values.

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.

149 150 151 152 153 154 155
To in-place update the `localizations.dart` file using the default
values, you can just run:

```dart
dart dev/tools/gen_localizations.dart --overwrite
```

156 157 158

### Translations Status, Reporting Errors

159 160 161 162
The translations (the `.arb` files) in this directory are based on the
English translations in `material_en.arb`. Google contributes
translations for all the languages supported by this package.
(Googlers, for more details see <go/flutter-l10n>.)
163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192

Not all of the translations represented here have been vetted by
native speakers. The following translations have been reviewed by
native speakers on the Flutter team:

*  material_de.arb
*  material_en.arb, material_en_GB.arb, material_en_IE.arb, material_en_ZA.arb
*  material_fr.arb, material_fr_CA.arb
*  material_ja.arb
*  material_ru.arb

The others were automatically generated using the Google Translators
Toolkit. We are actively seeking review (by native speakers) for them.

If you have feedback about the translations please
[file an issue on the Flutter github repo](https://github.com/flutter/flutter/issues/new).


### See Also

The [Internationalizing Flutter Apps](https://flutter.io/tutorials/internationalization/)
tutorial describes how to use the internationlization APIs in an
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.

The Dart [intl](https://pub.dartlang.org/packages/intl)
package supports internationalization.