github/flutter
7
0
Fork 0
mirror of https://github.com/flutter/flutter.git synced 2025-06-03 00:51:18 +00:00
Code Issues Packages Projects Releases Wiki Activity

Cupertino localization step 10: update the flutter_localizations README (#30224)

Browse Source
This commit is contained in:
xster 2019-05-09 23:17:43 -07:00 committed by GitHub
parent 6d0e235cf8
commit 1ac813a5e6
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 48 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

86
packages/flutter_localizations/lib/src/l10n/README.md
View File

@ -1,9 +1,11 @@
# Material Library Localizations # Material and Cupertino Libraries Localizations
The `.arb` files in this directory contain localized values (primarily The `.arb` files in this directory contain localized values (primarily
strings) used by the material library. The `localizations.dart` file strings) used by the Material and Cupertino libraries. The
combines all of the localizations into a single Map that is `generated_material_localizations.dart` and
linked with the rest of flutter_localizations package. `generated_cupertino_localizations.dart` files combine all of the
localizations into a single Map that is linked with the rest of
flutter_localizations package.
If you're looking for information about internationalizing Flutter If you're looking for information about internationalizing Flutter
apps in general, see the apps in general, see the
@ -12,7 +14,7 @@ apps in general, see the
### Translations for one locale: .arb files ### Translations for one locale: .arb files
The Material library uses The Material and Cupertino libraries use
[Application Resource Bundle](https://code.google.com/p/arb/wiki/ApplicationResourceBundleSpecification) [Application Resource Bundle](https://code.google.com/p/arb/wiki/ApplicationResourceBundleSpecification)
files, which have a `.arb` extension, to store localized translations files, which have a `.arb` extension, to store localized translations
of messages, format strings, and other values. This format is also of messages, format strings, and other values. This format is also
@ -20,9 +22,9 @@ used by the Dart [intl](https://pub.dartlang.org/packages/intl)
package and it is supported by the package and it is supported by the
[Google Translators Toolkit](https://translate.google.com/toolkit). [Google Translators Toolkit](https://translate.google.com/toolkit).
The material library only depends on a small subset of the ARB format. The Material and Cupertino libraries only depend on a small subset
Each .arb file contains a single JSON table that maps from resource of the ARB format. Each .arb file contains a single JSON table that
IDs to localized values. maps from resource IDs to localized values.
Filenames contain the locale that the values have been translated Filenames contain the locale that the values have been translated
for. For example `material_de.arb` contains German translations, and for. For example `material_de.arb` contains German translations, and
@ -36,8 +38,8 @@ an additional file with a regional suffix is present, the regional
localizations are automatically merged with the language-specific ones. localizations are automatically merged with the language-specific ones.
The JSON table's keys, called resource IDs, are valid Dart variable The JSON table's keys, called resource IDs, are valid Dart variable
names. They correspond to methods from the `MaterialLocalizations` names. They correspond to methods from the `MaterialLocalizations` or
class. For example: `CupertinoLocalizations` classes. For example:
```dart ```dart
Widget build(BuildContext context) { Widget build(BuildContext context) {
@ -59,17 +61,21 @@ generated `localizations.dart` file. The Map is used by the
MaterialLocalizations class. MaterialLocalizations class.
### material_en.arb Defines all of the resource IDs ### material_en.arb and cupertino_en.arb Define all of the resource IDs
All of the `.arb` files whose names do not include a regional suffix All of the `material_*.arb` files whose names do not include a regional
contain translations for the same set of resource IDs as suffix contain translations for the same set of resource IDs as
`material_en.arb`. `material_en.arb`.
For each resource ID defined for English in material_en.arb, there is Similarly all of the `cupertino_*.arb` files whose names do not include
an additional resource with an '@' prefix. These '@' resources are not a regional suffix contain translations for the same set of resource IDs
used by the material library at run time, they just exist to inform as `cupertino_en.arb`.
translators about how the value will be used, and to inform the code
generator about what code to write. 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.
```dart ```dart
"cancelButtonLabel": "CANCEL", "cancelButtonLabel": "CANCEL",
@ -83,8 +89,8 @@ generator about what code to write.
### Values with Parameters, Plurals ### Values with Parameters, Plurals
A few of material translations contain `$variable` tokens. The A few of material translations contain `$variable` tokens. The
material library replaces these tokens with values at run-time. For Material and Cupertino libraries replace these tokens with values at
example: run-time. For example:
```dart ```dart
"aboutListTileTitle": "About $applicationName", "aboutListTileTitle": "About $applicationName",
@ -97,7 +103,7 @@ method instead of a simple getter:
MaterialLocalizations.of(context).aboutListTileTitle(yourAppTitle) MaterialLocalizations.of(context).aboutListTileTitle(yourAppTitle)
``` ```
The names of the `$variable` tokens match the names of the The names of the `$variable` tokens must match the names of the
`MaterialLocalizations` method parameters. `MaterialLocalizations` method parameters.
@ -123,11 +129,15 @@ the "Other" suffix. For example the English translations
"selectedRowCountTitleOther": "$selectedRowCount items selected", "selectedRowCountTitleOther": "$selectedRowCount items selected",
``` ```
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.
### scriptCategory and timeOfDayFormat ### scriptCategory and timeOfDayFormat for Material library
The values of these resource IDs are not translations, they're keywords that In `material_en.arb`, the values of these resource IDs are not
help define an app's text theme and time picker layout respectively. translations, they're keywords that help define an app's text theme
and time picker layout respectively.
The value of `timeOfDayFormat` defines how a time picker displayed by The value of `timeOfDayFormat` defines how a time picker displayed by
[showTimePicker()](https://docs.flutter.io/flutter/material/showTimePicker.html) [showTimePicker()](https://docs.flutter.io/flutter/material/showTimePicker.html)
@ -145,43 +155,43 @@ section in the Material spec. The Material theme uses the
[Typography.geometryThemeFor](https://docs.flutter.io/flutter/material/Typography/geometryThemeFor.html). [Typography.geometryThemeFor](https://docs.flutter.io/flutter/material/Typography/geometryThemeFor.html).
### Generated file localizations.dart: all of the localizations as a Map ### 'generated_*_localizations.dart': all of the localizations as a Map
If you look at the comment at the top of `localizations.dart` you'll If you look at the comment at the top of the `generated_material_localizations.dart`
see that it was manually generated using a `dev/tools/localization` app called and `generated_cupertino_localizations.dart` files, you'll
`gen_localizations`. see that it was manually generated using a `dev/tools/localizations`
app called `gen_localizations`.
You can see what that script would generate by running this command: You can see what that script would generate by running this command:
```dart ```dart
dart dev/tools/localization/gen_localizations.dart packages/flutter_localizations/lib/src/l10n material dart dev/tools/localizations/gen_localizations.dart packages/flutter_localizations/lib/src/l10n material
``` ```
The gen_localizations app just combines the contents of all of the The gen_localizations app just combines the contents of all of the
.arb files into a single `Map` that has entries for each .arb .arb files into a single `Map` per library that has entries for each .arb
file's locale. The `MaterialLocalizations` class implementation uses file's locale. The `MaterialLocalizations` and `CupertinoLocalizations`
this Map to implement the methods that lookup localized resource class implementations use these Maps to implement the methods that lookup localized resource values.
values.
The gen_localizations app must be run by hand after .arb files have 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, 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 the second is the file name prefix (the file name less the locale
suffix) for the .arb files in this directory. suffix) for the .arb files in this directory.
To in-place update the `localizations.dart` file using the default To in-place update the generated localizations file using the default
values, you can just run: values, you can just run:
```dart ```dart
dart dev/tools/localization/gen_localizations.dart --overwrite dart dev/tools/localizations/gen_localizations.dart --overwrite
``` ```
### Translations Status, Reporting Errors ### Translations Status, Reporting Errors
The translations (the `.arb` files) in this directory are based on the The translations (the `.arb` files) in this directory are based on the
English translations in `material_en.arb`. Google contributes English translations in `material_en.arb` and `cupertino_en.arb`.
translations for all the languages supported by this package. Google contributes translations for all the languages supported by
(Googlers, for more details see <go/flutter-l10n>.) this package. (Googlers, for more details see <go/flutter-l10n>.)
If you have feedback about the translations please If you have feedback about the translations please
[file an issue on the Flutter github repo](https://github.com/flutter/flutter/issues/new?template=BUG.md). [file an issue on the Flutter github repo](https://github.com/flutter/flutter/issues/new?template=BUG.md).