supportedLocales property

The list of locales that this app has been localized for.

By default only the American English locale is supported. Apps should configure this list to match the locales they support.

This list must not null. Its default value is just [const Locale('en', 'US')].

The order of the list matters. The default locale resolution algorithm, basicLocaleListResolution, attempts to match by the following priority:

1. Locale.languageCode, Locale.scriptCode, and Locale.countryCode
2. Locale.languageCode and Locale.scriptCode only
3. Locale.languageCode and Locale.countryCode only
4. Locale.languageCode only
5. Locale.countryCode only when all preferred locales fail to match
6. Returns the first element of supportedLocales as a fallback

When more than one supported locale matches one of these criteria, only the first matching locale is returned.

The default locale resolution algorithm can be overridden by providing a value for localeListResolutionCallback. The provided basicLocaleListResolution is optimized for speed and does not implement a full algorithm (such as the one defined in Unicode TR35) that takes distances between languages into account.

When supporting languages with more than one script, it is recommended to specify the Locale.scriptCode explicitly. Locales may also be defined without Locale.countryCode to specify a generic fallback for a particular script.

A fully supported language with multiple scripts should define a generic language-only locale (e.g. 'zh'), language+script only locales (e.g. 'zh_Hans' and 'zh_Hant'), and any language+script+country locales (e.g. 'zh_Hans_CN'). Fully defining all of these locales as supported is not strictly required but allows for proper locale resolution in the most number of cases. These locales can be specified with the Locale.fromSubtags constructor:

// Full Chinese support for CN, TW, and HK
supportedLocales: <Locale>[
  const Locale.fromSubtags(languageCode: 'zh'), // generic Chinese 'zh'
  const Locale.fromSubtags(languageCode: 'zh', scriptCode: 'Hans'), // generic simplified Chinese 'zh_Hans'
  const Locale.fromSubtags(languageCode: 'zh', scriptCode: 'Hant'), // generic traditional Chinese 'zh_Hant'
  const Locale.fromSubtags(languageCode: 'zh', scriptCode: 'Hans', countryCode: 'CN'), // 'zh_Hans_CN'
  const Locale.fromSubtags(languageCode: 'zh', scriptCode: 'Hant', countryCode: 'TW'), // 'zh_Hant_TW'
  const Locale.fromSubtags(languageCode: 'zh', scriptCode: 'Hant', countryCode: 'HK'), // 'zh_Hant_HK'
],

Omitting some these fallbacks may result in improperly resolved edge-cases, for example, a simplified Chinese user in Taiwan ('zh_Hans_TW') may resolve to traditional Chinese if 'zh_Hans' and 'zh_Hans_CN' are omitted.

See also:

• MaterialApp.supportedLocales, which sets the supportedLocales of the WidgetsApp it creates.
• localeResolutionCallback, an app callback that resolves the app's locale when the device's locale changes.
• localizationsDelegates, which collectively define all of the localized resources used by this app.
• basicLocaleListResolution, the default locale resolution algorithm.