Cupertino localization step 10: update the flutter_localizations README (#30224)
diff --git a/packages/flutter_localizations/lib/src/l10n/README.md b/packages/flutter_localizations/lib/src/l10n/README.md
index 0892171..f592652 100644
--- a/packages/flutter_localizations/lib/src/l10n/README.md
+++ b/packages/flutter_localizations/lib/src/l10n/README.md
@@ -1,9 +1,11 @@
-# Material Library Localizations
+# Material and Cupertino Libraries Localizations
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 Map that is
-linked with the rest of flutter_localizations package.
+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.
If you're looking for information about internationalizing Flutter
apps in general, see the
@@ -12,7 +14,7 @@
### 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)
files, which have a `.arb` extension, to store localized translations
of messages, format strings, and other values. This format is also
@@ -20,9 +22,9 @@
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.
+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
@@ -36,8 +38,8 @@
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:
+names. They correspond to methods from the `MaterialLocalizations` or
+`CupertinoLocalizations` classes. For example:
```dart
Widget build(BuildContext context) {
@@ -59,17 +61,21 @@
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
-contain translations for the same set of resource IDs as
+All of the `material_*.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, and to inform the code
-generator about what code to write.
+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.
```dart
"cancelButtonLabel": "CANCEL",
@@ -83,8 +89,8 @@
### 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:
+Material and Cupertino libraries replace these tokens with values at
+run-time. For example:
```dart
"aboutListTileTitle": "About $applicationName",
@@ -97,7 +103,7 @@
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.
@@ -123,11 +129,15 @@
"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
-help define an app's text theme and time picker layout respectively.
+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.
The value of `timeOfDayFormat` defines how a time picker displayed by
[showTimePicker()](https://docs.flutter.io/flutter/material/showTimePicker.html)
@@ -145,43 +155,43 @@
[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
-see that it was manually generated using a `dev/tools/localization` app called
-`gen_localizations`.
+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`.
You can see what that script would generate by running this command:
```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
-.arb files into a single `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.
+.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.
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.
-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:
```dart
-dart dev/tools/localization/gen_localizations.dart --overwrite
+dart dev/tools/localizations/gen_localizations.dart --overwrite
```
### Translations Status, Reporting Errors
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>.)
+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>.)
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).
