Skip to content

Commit 9139520

Browse files
mitrypbkonyi
andauthored
[gen_l10n] Add use-explicit-plural-values option (flutter#194816)
`flutter gen-l10n` currently maps the ICU explicit plural values `=0`, `=1` and `=2` to the CLDR plural categories `zero`, `one` and `two`. In many locales `Intl.pluralLogic` selects those categories for more than the exact number, so a message such as ``` {count, plural, =1{exactly one} other{{count} items}} ``` shows "exactly one" for 21, 31 and 101 in Ukrainian, and for 0 in French. In ICU and CLDR, an explicit value matches only that exact number and takes precedence over the plural categories. Because of the mapping, `=1` and `one` also cannot be used in the same message (one of them is dropped with an "overridden by a later plural part" warning), and explicit values other than 0, 1 and 2 are rejected. This PR adds an opt-in `use-explicit-plural-values` option (`l10n.yaml` and `--use-explicit-plural-values`). When it is enabled, explicit values are generated as exact checks in front of the `Intl.pluralLogic` call, and only the category cases are passed to `Intl.pluralLogic`: ```dart String _temp0 = count == 1 ? 'exactly one' : intl.Intl.pluralLogic( count, locale: localeName, other: '$count items', ); ``` With the option enabled: - Any non-negative integer can be used as an explicit value, for example `=3` or `=10`. - An explicit value and the category of the same name, such as `=1` and `one`, can be used in the same message without a warning. - Category cases behave exactly as before, including the exact-number handling `Intl.pluralLogic` already applies to `zero`, `one` and `two`. The option defaults to `false`, and the generated code is unchanged when it is off. As discussed in flutter#84291, changing the default would be a breaking change, so that is left for a follow-up. The generated code uses conditional expressions rather than a switch expression so that it still compiles in packages that use older language versions. Fixes flutter#84291 Related: flutter#133276 (in Latvian, `=0` is currently also used for 10-20 because it is mapped to the `zero` category; this no longer happens when the option is enabled) Website documentation: flutter/website#13993 ## Tests - `dart test test/general.shard/generate_localizations_test.dart test/general.shard/build_system/targets/localizations_test.dart test/commands.shard/hermetic/generate_localizations_test.dart test/general.shard/message_parser_test.dart test/integration.shard/gen_l10n_test.dart` - `dart analyze --fatal-infos` and `dart format --output=none --set-exit-if-changed` on the changed files - Checked manually in a sample app with `en`, `fr` and `uk` ARB files. With the option enabled, `=1` is used only for 1 in Ukrainian (21, 31 and 101 fall through to the category cases) and `=0` is used for 0 in French. With the option disabled, the behavior is unchanged. ## AI assistance disclosure AI tools (Cursor) assisted with the implementation, tests and verification. ## Pre-launch Checklist - [x] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [x] I read the [AI contribution guidelines] and understand my responsibilities, or I am not using AI tools. - [x] I read the [Tree Hygiene] wiki page, which explains my responsibilities. - [x] I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement]. - [x] I signed the [CLA]. - [x] I listed at least one issue that this PR fixes in the description above. - [x] I updated/added relevant in-code documentation (doc comments with `///`). - [x] If this PR introduces a new feature or capability, I created and linked a website documentation issue or PR in [flutter/website] (or verified none is needed). - [x] I added new tests to check the change I am making, or this PR is [test-exempt]. - [x] I followed the [breaking change policy] and added [Data Driven Fixes] where supported. - [x] All existing and new tests are passing. If you need help, consider asking for advice on the #hackers-new channel on [Discord]. If this change needs to override an active code freeze, provide a comment explaining why. The code freeze workflow can be overridden by code reviewers. See pinned issues for any active code freezes with guidance. **Note**: The Flutter team is currently trialing the use of [Gemini Code Assist for GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code). Comments from the `gemini-code-assist` bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed. <!-- Links --> [Contributor Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview [AI contribution guidelines]: https://github.com/flutter/flutter/blob/main/CONTRIBUTING.ai.md [Tree Hygiene]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md [test-exempt]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests [Flutter Style Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md [Features we expect every widget to implement]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement [CLA]: https://cla.developers.google.com/ [flutter/tests]: https://github.com/flutter/tests [flutter/website]: https://github.com/flutter/website [breaking change policy]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes [Discord]: https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md [Data Driven Fixes]: https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md --------- Co-authored-by: Ben Konyi <[email protected]>
1 parent 9fd9852 commit 9139520

7 files changed

Lines changed: 318 additions & 5 deletions

File tree

‎packages/flutter_tools/lib/src/commands/generate_localizations.dart‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -204,6 +204,14 @@ class GenerateLocalizationsCommand extends FlutterCommand {
204204
'use-named-parameters',
205205
help: 'Whether or not to use named parameters for the generated localization methods.',
206206
);
207+
argParser.addFlag(
208+
'use-explicit-plural-values',
209+
help:
210+
'Whether explicit plural cases such as "=1" match only that exact value and take '
211+
'precedence over plural categories such as "one", as specified by ICU. '
212+
'By default this is false for backwards compatibility, in which case "=0", "=1" '
213+
'and "=2" are treated as "zero", "one" and "two".',
214+
);
207215
}
208216

209217
final ToolContext _toolContext;

‎packages/flutter_tools/lib/src/localizations/gen_l10n.dart‎

Lines changed: 46 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,7 @@ Future<LocalizationsGenerator> generateLocalizations({
7474
suppressWarnings: options.suppressWarnings,
7575
useRelaxedSyntax: options.relaxSyntax,
7676
useNamedParameters: options.useNamedParameters,
77+
useExplicitPluralValues: options.useExplicitPluralValues,
7778
)
7879
..loadResources()
7980
..writeOutputFiles(isFromYaml: true, useCRLF: useCRLF);
@@ -528,6 +529,7 @@ class LocalizationsGenerator {
528529
bool suppressWarnings = false,
529530
bool useRelaxedSyntax = false,
530531
bool useNamedParameters = false,
532+
bool useExplicitPluralValues = false,
531533
}) {
532534
final Directory projectDirectory = projectDirFromPath(fileSystem, projectPathString);
533535
final Directory inputDirectory = inputDirectoryFromPath(
@@ -567,6 +569,7 @@ class LocalizationsGenerator {
567569
suppressWarnings: suppressWarnings,
568570
useRelaxedSyntax: useRelaxedSyntax,
569571
useNamedParameters: useNamedParameters,
572+
useExplicitPluralValues: useExplicitPluralValues,
570573
);
571574
}
572575

@@ -593,6 +596,7 @@ class LocalizationsGenerator {
593596
this.suppressWarnings = false,
594597
this.useRelaxedSyntax = false,
595598
this.useNamedParameters = false,
599+
this.useExplicitPluralValues = false,
596600
});
597601

598602
final FileSystem _fs;
@@ -741,6 +745,14 @@ class LocalizationsGenerator {
741745
/// ```
742746
final bool useNamedParameters;
743747

748+
/// Whether explicit plural values such as `=1` match only that exact value.
749+
///
750+
/// If this is true, an explicit `=N` plural case is compared against the
751+
/// count before the plural category (`zero`, `one`, `two`, `few`, `many`,
752+
/// `other`) is resolved, and any non-negative integer is allowed for `N`.
753+
/// Otherwise `=0`, `=1` and `=2` are treated as `zero`, `one` and `two`.
754+
final bool useExplicitPluralValues;
755+
744756
static bool _isNotReadable(FileStat fileStat) {
745757
final String rawStatString = fileStat.modeString();
746758
// Removes potential prepended permission bits, such as '(suid)' and '(guid)'.
@@ -1297,6 +1309,8 @@ class LocalizationsGenerator {
12971309

12981310
case ST.pluralExpr:
12991311
final pluralLogicArgs = <String, String>{};
1312+
// Explicit values in reverse source order, keyed by their integer value.
1313+
final explicitPluralArgs = <int, String>{};
13001314
// Recall that pluralExpr are of the form
13011315
// pluralExpr := "{" ID "," "plural" "," pluralParts "}"
13021316
assert(node.children[1].type == ST.identifier);
@@ -1308,7 +1322,8 @@ class LocalizationsGenerator {
13081322
for (final Node pluralPart in pluralParts.children.reversed) {
13091323
String pluralCase;
13101324
Node pluralMessage;
1311-
if (pluralPart.children[0].value == '=') {
1325+
final isExplicitValue = pluralPart.children[0].value == '=';
1326+
if (isExplicitValue) {
13121327
assert(pluralPart.children[1].type == ST.number);
13131328
assert(pluralPart.children[3].type == ST.message);
13141329
pluralCase = pluralPart.children[1].value!;
@@ -1322,7 +1337,23 @@ class LocalizationsGenerator {
13221337
pluralCase = pluralPart.children[0].value!;
13231338
pluralMessage = pluralPart.children[2];
13241339
}
1325-
if (!pluralLogicArgs.containsKey(pluralCases[pluralCase])) {
1340+
final int? explicitValue = useExplicitPluralValues && isExplicitValue
1341+
? int.tryParse(pluralCase)
1342+
: null;
1343+
if (useExplicitPluralValues && isExplicitValue && explicitValue == null) {
1344+
throw L10nParserException(
1345+
'''
1346+
The plural case "=$pluralCase" is too large to be represented as an integer.''',
1347+
_inputFileNames[locale]!,
1348+
message.resourceId,
1349+
translationForMessage,
1350+
pluralPart.positionInMessage,
1351+
);
1352+
}
1353+
if (explicitValue != null && !explicitPluralArgs.containsKey(explicitValue)) {
1354+
explicitPluralArgs[explicitValue] = generateVariables(pluralMessage);
1355+
} else if (explicitValue == null &&
1356+
!pluralLogicArgs.containsKey(pluralCases[pluralCase])) {
13261357
final String pluralPartExpression = generateVariables(pluralMessage);
13271358
final String? transformedPluralCase = pluralCases[pluralCase];
13281359
// A valid plural case is one of "=0", "=1", "=2", "zero", "one", "two", "few", "many", or "other".
@@ -1351,7 +1382,19 @@ The plural cases must be one of "=0", "=1", "=2", "zero", "one", "two", "few", "
13511382
pluralVariableTemplate
13521383
.replaceAll('@(varName)', tempVarName)
13531384
.replaceAll('@(count)', identifier.value!)
1354-
.replaceAll('@(pluralLogicArgs)', pluralLogicArgs.values.join('\n')),
1385+
.replaceAll('@(pluralLogicArgs)', pluralLogicArgs.values.join('\n'))
1386+
// Must run last and only once, so message text is never rewritten.
1387+
.replaceFirst(
1388+
'@(explicitPluralCases)',
1389+
explicitPluralArgs.entries
1390+
.toList()
1391+
.reversed
1392+
.map(
1393+
(MapEntry<int, String> entry) =>
1394+
'${identifier.value!} == ${entry.key}\n ? ${entry.value}\n : ',
1395+
)
1396+
.join(),
1397+
),
13551398
);
13561399
return '\$$tempVarName';
13571400

‎packages/flutter_tools/lib/src/localizations/gen_l10n_templates.dart‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -149,7 +149,7 @@ const methodWithNamedParameterTemplate = '''
149149
}''';
150150

151151
const pluralVariableTemplate = '''
152-
String @(varName) = intl.Intl.pluralLogic(
152+
String @(varName) = @(explicitPluralCases)intl.Intl.pluralLogic(
153153
@(count),
154154
locale: localeName,
155155
@(pluralLogicArgs)

‎packages/flutter_tools/lib/src/localizations/localizations_utils.dart‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -343,6 +343,7 @@ class LocalizationOptions {
343343
bool? suppressWarnings,
344344
bool? relaxSyntax,
345345
bool? useNamedParameters,
346+
bool? useExplicitPluralValues,
346347
}) : templateArbFile = templateArbFile ?? 'app_en.arb',
347348
outputLocalizationFile = outputLocalizationFile ?? 'app_localizations.dart',
348349
outputClass = outputClass ?? 'AppLocalizations',
@@ -353,7 +354,8 @@ class LocalizationOptions {
353354
useEscaping = useEscaping ?? false,
354355
suppressWarnings = suppressWarnings ?? false,
355356
relaxSyntax = relaxSyntax ?? false,
356-
useNamedParameters = useNamedParameters ?? false;
357+
useNamedParameters = useNamedParameters ?? false,
358+
useExplicitPluralValues = useExplicitPluralValues ?? false;
357359

358360
/// The `--arb-dir` argument.
359361
///
@@ -456,6 +458,15 @@ class LocalizationOptions {
456458
///
457459
/// Defaults to `false`.
458460
final bool useNamedParameters;
461+
462+
/// The `use-explicit-plural-values` argument.
463+
///
464+
/// Whether explicit plural values such as `=1` match only that exact value
465+
/// and take precedence over plural categories such as `one`. If false,
466+
/// `=0`, `=1` and `=2` are treated as `zero`, `one` and `two`.
467+
///
468+
/// Defaults to `false`.
469+
final bool useExplicitPluralValues;
459470
}
460471

461472
/// Parse the localizations configuration options from [file].
@@ -527,6 +538,7 @@ LocalizationOptions parseLocalizationsOptionsFromYAML({
527538
suppressWarnings: _tryReadBool(yamlNode, 'suppress-warnings', logger),
528539
relaxSyntax: _tryReadBool(yamlNode, 'relax-syntax', logger),
529540
useNamedParameters: _tryReadBool(yamlNode, 'use-named-parameters', logger),
541+
useExplicitPluralValues: _tryReadBool(yamlNode, 'use-explicit-plural-values', logger),
530542
);
531543
}
532544

@@ -569,6 +581,7 @@ LocalizationOptions parseLocalizationsOptionsFromCommand({
569581
useEscaping: command.boolArg('use-escaping'),
570582
suppressWarnings: command.boolArg('suppress-warnings'),
571583
useNamedParameters: command.boolArg('use-named-parameters'),
584+
useExplicitPluralValues: command.boolArg('use-explicit-plural-values'),
572585
);
573586
}
574587

‎packages/flutter_tools/test/commands.shard/hermetic/generate_localizations_test.dart‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -431,6 +431,31 @@ format: false
431431
);
432432
});
433433

434+
testWithoutContext('use-explicit-plural-values is forwarded from the command line', () async {
435+
final File arbFile = fileSystem.file(fileSystem.path.join('lib', 'l10n', 'app_en.arb'))
436+
..createSync(recursive: true);
437+
arbFile.writeAsStringSync('''
438+
{
439+
"itemCount": "{count,plural, =1{exactly one} one{{count} item} other{{count} items}}",
440+
"@itemCount": {
441+
"description": "Sample description"
442+
}
443+
}''');
444+
final File pubspecFile = fileSystem.file('pubspec.yaml')..createSync();
445+
pubspecFile.writeAsStringSync(BasicProjectWithFlutterGen().pubspec);
446+
final command = GenerateLocalizationsCommand(toolContext: toolContext);
447+
await createTestCommandRunner(command)
448+
.run(<String>['gen-l10n', '--use-explicit-plural-values']);
449+
450+
final File outputFile = fileSystem.file(
451+
fileSystem.path.join('lib', 'l10n', 'app_localizations_en.dart'),
452+
);
453+
expect(outputFile.existsSync(), isTrue);
454+
final String content = outputFile.readAsStringSync();
455+
expect(content, contains('count == 1'));
456+
expect(content, contains(r"one: '$count item',"));
457+
});
458+
434459
testWithoutContext('throw when generate: false when run with l10n.yaml', () async {
435460
final File arbFile = fileSystem.file(fileSystem.path.join('lib', 'l10n', 'app_en.arb'))
436461
..createSync(recursive: true);

‎packages/flutter_tools/test/general.shard/build_system/targets/localizations_test.dart‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,7 @@ use-deferred-loading: true
4646
preferred-supported-locales: en_US
4747
required-resource-attributes: false
4848
nullable-getter: false
49+
use-explicit-plural-values: true
4950
''');
5051

5152
final LocalizationOptions options = parseLocalizationsOptionsFromYAML(
@@ -66,6 +67,7 @@ nullable-getter: false
6667
expect(options.preferredSupportedLocales, <String>['en_US']);
6768
expect(options.requiredResourceAttributes, false);
6869
expect(options.nullableGetter, false);
70+
expect(options.useExplicitPluralValues, true);
6971
});
7072

7173
testWithoutContext('parseLocalizationsOptions refuses synthetic-package: true', () async {

0 commit comments

Comments
 (0)