Skip to content

Commit 490fe28

Browse files
harperl-lgtmharperl-lgtm
authored
Updated instructions for adding new localized messages. (#115390)
1 parent cacf1d2 commit 490fe28

File tree

2 files changed

+65
-62
lines changed

2 files changed

+65
-62
lines changed

‎packages/flutter/lib/src/material/material_localizations.dart

Lines changed: 2 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -14,64 +14,8 @@ import 'typography.dart';
1414

1515
// ADDING A NEW STRING
1616
//
17-
// If you (someone contributing to the Flutter framework) want to add a new
18-
// string to the MaterialLocalizations object (e.g. because you've added a new
19-
// widget and it has a tooltip), follow these steps:
20-
//
21-
// 1. Add the new getter to MaterialLocalizations below.
22-
//
23-
// 2. Implement a default value in DefaultMaterialLocalizations below.
24-
//
25-
// 3. Add a test to test/material/localizations_test.dart that verifies that
26-
// this new value is implemented.
27-
//
28-
// 4. Update the flutter_localizations package. To add a new string to the
29-
// flutter_localizations package, you must first add it to the English
30-
// translations (lib/src/l10n/material_en.arb), including a description.
31-
//
32-
// Then you need to add new entries for the string to all of the other
33-
// language locale files by running:
34-
//
35-
// dart dev/tools/localization/bin/gen_missing_localizations.dart
36-
//
37-
// Which will copy the english strings into the other locales as placeholders
38-
// until they can be translated.
39-
//
40-
// Finally you need to re-generate lib/src/l10n/localizations.dart by running:
41-
//
42-
// dart dev/tools/localization/bin/gen_localizations.dart --overwrite
43-
//
44-
// There is a README file with further information in the lib/src/l10n/
45-
// directory.
46-
//
47-
// 5. If you are a Google employee, you should then also follow the instructions
48-
// at go/flutter-l10n. If you're not, don't worry about it.
49-
//
50-
// UPDATING AN EXISTING STRING
51-
//
52-
// If you (someone contributing to the Flutter framework) want to modify an
53-
// existing string in the MaterialLocalizations objects, follow these steps:
54-
//
55-
// 1. Modify the default value of the relevant getter(s) in
56-
// DefaultMaterialLocalizations below.
57-
//
58-
// 2. Update the flutter_localizations package. Modify the out-of-date English
59-
// strings in lib/src/l10n/material_en.arb.
60-
//
61-
// You also need to re-generate lib/src/l10n/localizations.dart by running:
62-
//
63-
// dart dev/tools/localization/bin/gen_localizations.dart --overwrite
64-
//
65-
// This script may result in your updated getters being created in newer
66-
// locales and set to the old value of the strings. This is to be expected.
67-
// Leave them as they were generated, and they will be picked up for
68-
// translation.
69-
//
70-
// There is a README file with further information in the lib/src/l10n/
71-
// directory.
72-
//
73-
// 3. If you are a Google employee, you should then also follow the instructions
74-
// at go/flutter-l10n. If you're not, don't worry about it.
17+
// Please refer to instructions in this markdown file
18+
// (packages/flutter_localizations/README.md)
7519

7620
/// Defines the localized resource values used by the Material widgets.
7721
///

‎packages/flutter_localizations/README.md

Lines changed: 63 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -15,11 +15,46 @@ and it has a tooltip), follow these steps (these instructions are for
1515
`MaterialLocalizations`, but apply equally to `CupertinoLocalizations`
1616
and `WidgetsLocalizations`, with appropriate name substitutions):
1717

18-
1. Add the new getter to the localizations class `MaterialLocalizations`,
19-
in `flutter_localizations/lib/src/material_localizations.dart`.
18+
1. ### For messages without parameters, add new getter
19+
```
20+
String get showMenuTooltip;
21+
```
22+
to the localizations class `MaterialLocalizations`,
23+
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);
24+
25+
### For messages with parameters, add new function
26+
```
27+
String aboutListTileTitle(String applicationName);
28+
```
29+
to the same localization class.
30+
31+
2. Implement a default return value in `DefaultMaterialLocalizations` in
32+
the same file as in step 1.
2033

21-
2. Implement a default value in `DefaultMaterialLocalizations` in
22-
`flutter_localizations/lib/src/material_localizations.dart`
34+
### Messages without parameters:
35+
```
36+
@override
37+
String get showMenuTooltip => 'Show menu';
38+
```
39+
### Messages with parameters:
40+
```
41+
@override
42+
String aboutListTileTitle(String applicationName) => 'About $applicationName';
43+
```
44+
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:
45+
46+
```
47+
/// The raw version of [aboutListTileTitle], with `$applicationName` verbatim
48+
/// in the string.
49+
@protected
50+
String get aboutListTileTitleRaw;
51+
52+
@override
53+
String aboutListTileTitle(String applicationName) {
54+
final String text = aboutListTileTitleRaw;
55+
return text.replaceFirst(r'$applicationName', applicationName);
56+
}
57+
```
2358

2459
3. Add a test to `test/material/localizations_test.dart` that verifies that
2560
this new value is implemented.
@@ -28,6 +63,23 @@ and `WidgetsLocalizations`, with appropriate name substitutions):
2863
`flutter_localizations` package, you must first add it to the English
2964
translations (`lib/src/l10n/material_en.arb`), including a description.
3065

66+
### Messages without parameters:
67+
```
68+
"showMenuTooltip": "Show menu",
69+
"@showMenuTooltip": {
70+
"description": "The tooltip for the button that shows a popup menu."
71+
},
72+
```
73+
74+
### Messages with parameters:
75+
```
76+
"aboutListTileTitle": "About $applicationName",
77+
"@aboutListTileTitle": {
78+
"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.",
79+
"parameters": "applicationName"
80+
},
81+
```
82+
3183
Then you need to add new entries for the string to all of the other
3284
language locale files by running:
3385
```
@@ -41,6 +93,13 @@ and `WidgetsLocalizations`, with appropriate name substitutions):
4193
dart dev/tools/localization/bin/gen_localizations.dart --overwrite
4294
```
4395

96+
If you got an error when running this command, [this issue](https://github.com/flutter/flutter/issues/104601) might be helpful.
97+
98+
TL;DR: If you got the same type of errors as discussed in the issue, run this instead:
99+
```
100+
dart dev/tools/localization/bin/gen_localizations.dart --overwrite --remove-undefined
101+
```
102+
44103
There is a [localization README](./lib/src/l10n/README.md) file with further
45104
information in the `lib/src/l10n/` directory.
46105

0 commit comments

Comments
 (0)