Add material/18n/README.md (#12359)
This commit is contained in:
Hans Muller
GitHub
parent
49499457f2
commit
528d28ba03
184
packages/flutter/lib/src/material/i18n/README.md
Normal file
184
packages/flutter/lib/src/material/i18n/README.md
Normal file
@ -0,0 +1,184 @@
|
|||||||
|
# Material Library Internationalization
|
||||||
|
|
||||||
|
The `.arb` files in this directory contain localized values (primarily
|
||||||
|
strings) used by the material library. The `localizations.dart` file
|
||||||
|
combines all of the localizations into a single Dart Map that is
|
||||||
|
linked with the rest of the material library.
|
||||||
|
|
||||||
|
If you're looking for information about internationalizing Flutter
|
||||||
|
apps in general, see th
|
||||||
|
[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
|
||||||
|
`cancelButtonLabel`. They're all represented by the Dart `Map` in the
|
||||||
|
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",
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
### Generated file localizations.dart: all of the localizations as a Dart Map
|
||||||
|
|
||||||
|
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
|
||||||
|
`gen_localizations` roughly like this:
|
||||||
|
|
||||||
|
```dart
|
||||||
|
dev/tools/gen_localizations.dart packages/flutter/lib/src/material/i18n material
|
||||||
|
```
|
||||||
|
|
||||||
|
The gen_localizations app just combines the contents of all of the
|
||||||
|
.arb files into a single Dart `Map` that has entries for each .arb
|
||||||
|
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.
|
||||||
|
|
||||||
|
|
||||||
|
### Translations Status, Reporting Errors
|
||||||
|
|
||||||
|
The transltations (the `.arb` files) in this directory are based on
|
||||||
|
the english translations in `material_en.arb`. As noted earlier,
|
||||||
|
material_en.arb, contains a small amount of descriptive information
|
||||||
|
for each resource ID, under the companion resources whose IDs begin
|
||||||
|
with '@'.
|
||||||
|
|
||||||
|
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.
|
||||||
Loading…
x
Reference in New Issue
Block a user