Document the use-explicit-plural-values gen-l10n option #13993

Related code pull request or issue

flutter/flutter#194816

Feature summary

flutter/flutter#194816 adds an opt-in use-explicit-plural-values option to flutter gen-l10n (l10n.yaml and --use-explicit-plural-values).

Today, gen-l10n maps the explicit plural values =0, =1 and =2 to the plural categories zero, one and two. In many locales those categories cover more than the exact number, so =1{1 item} is also shown for 21, 31 and 101 in Ukrainian, and for 0 in French. With the option enabled, explicit values match only that exact number and take precedence over the categories, as specified by ICU. Any non-negative integer can be used (=3, =10), and =1 and one can be used in the same message. The option defaults to false.

Type of documentation needed

• New conceptual page or guide
• Update to an existing guide on docs.flutter.dev
• Cookbook recipe or practical code sample
• CLI or tooling documentation
• Platform support or integration guide
• Breaking change migration guide

Code snippet or usage example

// l10n.yaml
// use-explicit-plural-values: true
//
// app_uk.arb
// "items": "{count, plural, =0{Немає елементів} =1{Рівно один елемент} one{{count} елемент} few{{count} елементи} many{{count} елементів} other{{count} елемента}}"
//
// Generated code:
String _temp0 = count == 0
    ? 'Немає елементів'
    : count == 1
    ? 'Рівно один елемент'
    : intl.Intl.pluralLogic(
        count,
        locale: localeName,
        other: '$count елемента',
        one: '$count елемент',
        few: '$count елементи',
        many: '$count елементів',
      );

Additional context or resources

Pages to update in sites/docs/src/content/ui/internationalization/index.md:

• The "Configuring the l10n.yaml file" table: add a [no-]use-explicit-plural-values row, for example: "Whether explicit plural cases such as =1 match only that exact value and take precedence over plural categories such as one, as specified by ICU. When false (the default), =0, =1 and =2 are treated as zero, one and two."
• The "Placeholders, plurals, and selects" section currently presents =0, =1 and =2 alongside few and many as if they were the same kind of case. It would help to explain the difference between explicit values (=N, exact match) and plural categories (zero, one, two, few, many, other, chosen by the locale's plural rules), and mention the new option.

Volunteer to help write this documentation

• Draft the documentation PR on docs.flutter.dev.