firka/flutter
firka/flutter
5
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Updated instructions for adding new localized messages. (#115390)

Browse Source
This commit is contained in:
harperl-lgtm 2022-11-16 15:44:14 -05:00 committed by GitHub
parent cacf1d298f
commit 490fe2835d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 65 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

60
packages/flutter/lib/src/material/material_localizations.dart
View File

@ -14,64 +14,8 @@ import 'typography.dart';
// ADDING A NEW STRING // ADDING A NEW STRING
// //
// If you (someone contributing to the Flutter framework) want to add a new // Please refer to instructions in this markdown file
// string to the MaterialLocalizations object (e.g. because you've added a new // (packages/flutter_localizations/README.md)
// widget and it has a tooltip), follow these steps:
//
// 1. Add the new getter to MaterialLocalizations below.
//
// 2. Implement a default value in DefaultMaterialLocalizations below.
//
// 3. Add a test to test/material/localizations_test.dart that verifies that
// this new value is implemented.
//
// 4. Update the flutter_localizations package. To add a new string to the
// flutter_localizations package, you must first add it to the English
// translations (lib/src/l10n/material_en.arb), including a description.
//
// Then you need to add new entries for the string to all of the other
// language locale files by running:
//
// dart dev/tools/localization/bin/gen_missing_localizations.dart
//
// Which will copy the english strings into the other locales as placeholders
// until they can be translated.
//
// Finally you need to re-generate lib/src/l10n/localizations.dart by running:
//
// dart dev/tools/localization/bin/gen_localizations.dart --overwrite
//
// There is a README file with further information in the lib/src/l10n/
// directory.
//
// 5. If you are a Google employee, you should then also follow the instructions
// at go/flutter-l10n. If you're not, don't worry about it.
//
// UPDATING AN EXISTING STRING
//
// If you (someone contributing to the Flutter framework) want to modify an
// existing string in the MaterialLocalizations objects, follow these steps:
//
// 1. Modify the default value of the relevant getter(s) in
// DefaultMaterialLocalizations below.
//
// 2. Update the flutter_localizations package. Modify the out-of-date English
// strings in lib/src/l10n/material_en.arb.
//
// You also need to re-generate lib/src/l10n/localizations.dart by running:
//
// dart dev/tools/localization/bin/gen_localizations.dart --overwrite
//
// This script may result in your updated getters being created in newer
// locales and set to the old value of the strings. This is to be expected.
// Leave them as they were generated, and they will be picked up for
// translation.
//
// There is a README file with further information in the lib/src/l10n/
// directory.
//
// 3. If you are a Google employee, you should then also follow the instructions
// at go/flutter-l10n. If you're not, don't worry about it.
/// Defines the localized resource values used by the Material widgets. /// Defines the localized resource values used by the Material widgets.
/// ///

67
packages/flutter_localizations/README.md
View File

@ -15,11 +15,46 @@ and it has a tooltip), follow these steps (these instructions are for
`MaterialLocalizations`, but apply equally to `CupertinoLocalizations` `MaterialLocalizations`, but apply equally to `CupertinoLocalizations`
and `WidgetsLocalizations`, with appropriate name substitutions): and `WidgetsLocalizations`, with appropriate name substitutions):
1. Add the new getter to the localizations class `MaterialLocalizations`, 1. ### For messages without parameters, add new getter
in `flutter_localizations/lib/src/material_localizations.dart`. ```
String get showMenuTooltip;
```
to the localizations class `MaterialLocalizations`,
in [`packages/flutter/lib/src/material/material_localizations.dart`](https://github.com/harperl-lgtm/flutter/blob/bottomSheetScrimFocus/packages/flutter/lib/src/material/material_localizations.dart);
2. Implement a default value in `DefaultMaterialLocalizations` in ### For messages with parameters, add new function
`flutter_localizations/lib/src/material_localizations.dart` ```
String aboutListTileTitle(String applicationName);
```
to the same localization class.
2. Implement a default return value in `DefaultMaterialLocalizations` in
the same file as in step 1.
### Messages without parameters:
```
@override
String get showMenuTooltip => 'Show menu';
```
### Messages with parameters:
```
@override
String aboutListTileTitle(String applicationName) => 'About $applicationName';
```
For messages with parameters, do also add the function to `GlobalMaterialLocalizations` in [`packages/flutter_localizations/lib/src/material_localizations.dart`](https://github.com/harperl-lgtm/flutter/blob/bottomSheetScrimFocus/packages/flutter_localizations/lib/src/material_localizations.dart), and add a raw getter as demonstrated below:
```
/// The raw version of [aboutListTileTitle], with `$applicationName` verbatim
/// in the string.
@protected
String get aboutListTileTitleRaw;
@override
String aboutListTileTitle(String applicationName) {
final String text = aboutListTileTitleRaw;
return text.replaceFirst(r'$applicationName', applicationName);
}
```
3. Add a test to `test/material/localizations_test.dart` that verifies that 3. Add a test to `test/material/localizations_test.dart` that verifies that
this new value is implemented. this new value is implemented.
@ -28,6 +63,23 @@ and `WidgetsLocalizations`, with appropriate name substitutions):
`flutter_localizations` package, you must first add it to the English `flutter_localizations` package, you must first add it to the English
translations (`lib/src/l10n/material_en.arb`), including a description. translations (`lib/src/l10n/material_en.arb`), including a description.
### Messages without parameters:
```
"showMenuTooltip": "Show menu",
"@showMenuTooltip": {
"description": "The tooltip for the button that shows a popup menu."
},
```
### Messages with parameters:
```
"aboutListTileTitle": "About $applicationName",
"@aboutListTileTitle": {
"description": "The default title for the drawer item that shows an about page for the application. The value of $applicationName is the name of the application, like GMail or Chrome.",
"parameters": "applicationName"
},
```
Then you need to add new entries for the string to all of the other Then you need to add new entries for the string to all of the other
language locale files by running: language locale files by running:
``` ```
@ -41,6 +93,13 @@ and `WidgetsLocalizations`, with appropriate name substitutions):
dart dev/tools/localization/bin/gen_localizations.dart --overwrite dart dev/tools/localization/bin/gen_localizations.dart --overwrite
``` ```
If you got an error when running this command, [this issue](https://github.com/flutter/flutter/issues/104601) might be helpful.
TL;DR: If you got the same type of errors as discussed in the issue, run this instead:
```
dart dev/tools/localization/bin/gen_localizations.dart --overwrite --remove-undefined
```
There is a [localization README](./lib/src/l10n/README.md) file with further There is a [localization README](./lib/src/l10n/README.md) file with further
information in the `lib/src/l10n/` directory. information in the `lib/src/l10n/` directory.