common_locale_data

This packages provides a type-safe and tree-shakable way to access translated common data.
The translations are extracted from the Common Locale Data Repository (CLDR).

It also includes helper function to use this data to format units, timezone names and locale names.

Available data

Translations for:

• measurement units in full and abbreviated forms including singular/plural modifications
• language names
• script, variant and unicode extension names
• territory and country names
• country subdivision names
• currency names, including singular/plural modifications
• weekday, month, era, period of day, in full and abbreviated forms
• calendar fields
• relative time fields
• time zones and example cities (or similar) for time zones

Functionality

Translations can be accessed via static member functions or dynamic maps.

Formatting functions are available for: units, currencies, relative time fields, timezones and locale identifiers.

Locale identifiers support parsing, canonicalization, adding and removing of likely subtags and formatting in various forms.

Tree-shaking

All the data and translations are stored as literal strings in the code. The APIs are designed to be tree-shakeable (mechanism to remove unused data from final program file). The final application's binaries won't include the translations for languages you don't use also it won't include types of data not used.

If you use locales individually (e.g. not stored in a collection), the tree-shaking will be optimal: only those data types of each locale are included that are actually used.

If members are accessed via static access the compiler can also reduce to only those fields (e.g. countries, currencies, languages) used. If dynamic access is used (via [] operator), then all fields are included.

If you store locales in a collection and then dynamically choose a collection member (or iterate over the collection), the compiler cannot determine which locales are actually used, so it will include the data for all the locales in the collection and for all teh data types used.

Compilation

To improve compilation speed locales need to be imported individually when using [common_locale_data]. For example for English: import 'package:common_locale_data/en.dart'; or for French: import 'package:common_locale_data/fr.dart';

You can import all locales via [CommonLocaleDataAll]. However this will increase compilation time significantly (10x over including just a couple of locales).

As long as you don't use the [CommonLocaleDataAll.locales] member to dynamically get locales the compiled file size is not affected. If you do use the [CommonLocaleDataAll.locales] member, all locales will be compiled in and the files size will become several 10's of MBs (depending on which types of data you use).

Source

The main CLDR data is extracted from this repository: https://github.com/unicode-org/cldr-json. Additional timezone related data is extracted from https://github.com/unicode-org/cldr and https://github.com/unicode-org/icu.

• CLDR version 46.0.0, variant: modern
• Unicode version 16.0.0
• TZDB version 2024b

Example

// Import specific locales instead of common_locale_data_all.dart to save
// significant compilation time.

import 'package:common_locale_data/de.dart';
import 'package:common_locale_data/en.dart';
import 'package:common_locale_data/en_gb.dart';
import 'package:common_locale_data/es.dart';
import 'package:common_locale_data/fr.dart';
import 'package:common_locale_data/zh_hans.dart';
import 'package:intl/intl.dart';

void main() {
  // Print basic version data for this package.
  print(
      'CLDR version: ${CommonLocaleData.cldrVersion} - ${CommonLocaleData.cldrVariant} ');
  print('Unicode version: ${CommonLocaleData.unicodeVersion}');
  print('ICU version: ${CommonLocaleData.icuVersion}');
  print('Timezone DB version: ${CommonLocaleData.tzdbVersion}');

  // For optimal tree-shaking you should explicitly choose the language you want
  // to use, e.g. `var cld = CommonLocaleDataEnGB()`.

  // However in practise you often want to dynamically select the users
  // preferred language from a set of supported languages.
  // You can use e.g. Platform.localeName for this purpose or
  // Intl.defaultLocale.

  // For illustration purposes we fix the set of desiredLocales here:
  var desiredLocales = ['nl', 'en-IR'];

  // Arbitrarily chosen set of supported locales.
  var supportedLocales = [
    CommonLocaleDataDe(),
    CommonLocaleDataEn(),
    CommonLocaleDataEnGB(),
    CommonLocaleDataEs(),
    CommonLocaleDataFr(),
    CommonLocaleDataZhHans(),
  ];

  // Get the best matching locale.
  var cld =
      LocaleMatcher.getBestCommonLocaleData(desiredLocales, supportedLocales)!;

  // Print the current locale name.
  print('');
  print(
      'Current localeId: ${cld.locale}: ${cld.localeDisplayName.formatWithExtensions(LocaleId.parse(cld.locale))}');

  // Units
  print('');
  print(cld.units.lengthMeter); // meters
  print(cld.units.lengthMeter.long(3.5)); // 3 meters
  print(cld.units.lengthMeter.long(3)); // 3 meters
  print(cld.units.lengthMeter.long(1)); // 1 meter

  print(cld.units.areaSquareMeter.long(3.5)); // 3 square meters
  print(cld.units.areaSquareMeter.short(3.5)); // 3 m²
  print(cld.units.areaSquareMeter.narrow(3.5)); // 3m²

  // Units with different formats
  print('');
  print(cld.units.areaSquareMeter.short(3541.53));
  print(cld.units.areaSquareMeter.short(3541.53,
      numberFormat: NumberFormat.decimalPatternDigits(decimalDigits: 2)));

  print(cld.units.areaSquareMeter
      .short(3541.53, numberFormat: NumberFormat.compact()));
  print(cld.units.areaSquareMeter
      .short(3541.53, numberFormat: NumberFormat.compactLong()));

  // Compound unit
  print('');
  print(cld.units.per.long(cld.units.electricAmpere.long.displayName,
      cld.units.durationSecond.long.displayName));
  print(cld.units.per.short(cld.units.electricAmpere.short.displayName,
      cld.units.durationSecond.short.displayName));
  print(cld.units.per.narrow(cld.units.electricAmpere.narrow.displayName,
      cld.units.durationSecond.narrow.displayName));
  print(cld.units.times.long(cld.units.electricOhm.long.displayName,
      cld.units.lengthMeter.long.displayName));
  print(cld.units.times.short(cld.units.electricOhm.short.displayName,
      cld.units.lengthMeter.short.displayName));
  print(cld.units.times.narrow(cld.units.electricOhm.narrow.displayName,
      cld.units.lengthMeter.narrow.displayName));

  // Date fields
  print('');
  print(cld.date.year.future.long(2)); // in 2 years
  print(cld.date.year.past.long(2)); // 2 years ago
  print(cld.date.year.next.long); // next year
  print(cld.date.year.previous.long); // last year

  // Territories
  print('');
  print(cld.territories.world); // world
  print(cld.territories.africa); // Africa
  print(cld.territories.$019); // Americas
  print(cld.territories.us); // South Africa

  // Territories with dynamic access: this will cause all territory data to be included in the binaries
  print(cld.territories.territories['019']); // Americas
  print(cld.territories.territories['US']); // United States

  // Languages names
  print('');
  print(cld.languages.en.name); // English
  print(cld.languages.zhHans.name); // Simplified Chinese
  print(cld.languages.und.name); // Undefined language

  // Languages with dynamic access: this will cause all territory data to be included in the binaries
  print(cld.languages['en']!.name); // English

  // Currencies
  print('');
  var currency = cld.currencies.usd;
  print(currency.displayName);
  print(currency.symbol);
  print(currency.symbolNarrow);
  print(currency.symbolVariant);

  print(currency(1.51));
  print(currency.short(1.51));
  print(currency.narrow(1.51));
  print(currency.variant(1.51));
  print(currency.iso(1.51));
  print(currency.hidden(1.51));

  print(currency.full(0));
  print(currency.full(0.51));
  print(currency.full(1));
  print(currency.full(1, decimalDigits: 1));
  print(currency.full(1.51));
  print(currency.full(2));
  print(currency.full(2.51));
  print(currency.full(3));
  print(currency.full(10));

  print(currency.short(1513));
  print(currency.short(1513, compact: true));
  print(currency.full(1513));
  print(currency.full(1513, compact: true));

  // Currencies with dynamic access: this will cause all territory data to be included in the binaries
  print(cld.currencies['eur']!.displayName);

  // Timezones
  print('');
  var zone = cld.timeZones.get('europe/athens', dateTime: DateTime(2017))!;

  print('code: ${zone.code}');
  print('canonicalCode: ${zone.canonicalCode}');
  print('ianaCode: ${zone.iana}');
  print('shortCode: ${zone.short}');
  print('exemplarCity: ${zone.exemplarCity}');
  print('country: ${zone.country}');
  print('metaZone code: ${zone.metaZone?.code}');
  print('isPrimaryOrSingle: ${zone.isPrimaryOrSingle}');
  print('dateRange: ${zone.dateRange}');

  // Different formats for timezone
  print('');
  var otherCountry = 'US';
  for (var style in TimeZoneStyle.values) {
    // The offset is manually obtained, use the timezone package to obtain it
    // for a given date/time.
    var zoneNameOwn = zone.format(style, Duration(hours: 2, minutes: 0));
    // also depend on the current country
    var zoneNameOther = zone.format(style, Duration(hours: 2, minutes: 0),
        country: otherCountry);
    print(
        '${style.name.padLeft(28)}: $zoneNameOwn${zoneNameOwn != zoneNameOther ? " (in $otherCountry: $zoneNameOther)".padLeft(50) : ""}');
  }

  // Demonstrate different timezone names at different times
  print('');
  print(cld.timeZones['America/Buenos_Aires']); // uses current DateTime
  print(cld.timeZones.get('America/Buenos_Aires', dateTime: DateTime(2008)));
  print(cld.timeZones
      .get('America/Buenos_Aires', dateTime: DateTime(2004, 6, 2)));

  // Locale manipulations
  print('');
  var localeId = LanguageId(lang: 'en', region: 'us');
  print('           toString: $localeId');
  print('            toBCP47: ${localeId.toBCP47()}');
  print('     toUnicodeBCP47: ${localeId.toUnicodeBCP47()}');
  print('      toUnicodeCLDR: ${localeId.toUnicodeCLDR()}');
  print('       canonicalize: ${localeId.canonicalize()}');
  print('   addLikelySubTags: ${localeId.addLikelySubTags()}');
  print('removeLikelySubTags: ${localeId.removeLikelySubTags()}');
  print(
      '  localeDisplayName: ${cld.localeDisplayName.formatWithExtensions(localeId)}');

  print('');
  localeId = LocaleId.parse(
      'en_US_POSIX_fonipa_u_co_phonebk_kb_yes_x_private@calendar=japanese;timezone=europe/paris###');
  print('           toString: $localeId');
  print('            toBCP47: ${localeId.toBCP47()}');
  print('     toUnicodeBCP47: ${localeId.toUnicodeBCP47()}');
  print('      toUnicodeCLDR: ${localeId.toUnicodeCLDR()}');
  print('       canonicalize: ${localeId.canonicalize()}');
  print('   addLikelySubTags: ${localeId.addLikelySubTags()}');
  print('removeLikelySubTags: ${localeId.removeLikelySubTags()}');
  print('  localeDisplayName: ${cld.localeDisplayName.format(localeId)}');
  print(
      '    with Extensions: ${cld.localeDisplayName.formatWithExtensions(localeId)}');

  // Locale Display Names
  print('');
  print(cld.localeDisplayName.format(LanguageId.parse('en-GB')));
  print(cld.localeDisplayName
      .format(LanguageId.parse('en-GB'), preferComposition: true));
  print(cld.localeDisplayName.format(LanguageId.parse('hi-Latn-GB')));
  print(cld.localeDisplayName.format(LanguageId.parse('hi-Latn-GB'),
      preferType: LocaleDisplayNameStyle.variant));
  print(cld.localeDisplayName.format(LanguageId.parse('hi-Latn-GB'),
      preferType: LocaleDisplayNameStyle.short));
  print(cld.localeDisplayName.format(LanguageId.parse('hi-Latn-GB'),
      preferType: LocaleDisplayNameStyle.menu));

  // format without extensions
  print(cld.localeDisplayName.format(LocaleId.parse(
      'en-GB-scoUse-fonipa-abl1943-u-cu-eur-ms-uksystem-rg-gband-sd-gblnd')));

  // format with extensions (and therefore pulls in subdivision, currency and timezone data)
  print(cld.localeDisplayName.formatWithExtensions(LocaleId.parse(
      'en-GB-scoUse-fonipa-abl1943-u-cu-eur-ms-ussystem-rg-gband-sd-gblnd')));
}

Supported languages/locales

By default all locales are included in this package. To change the included locales modify the tool\config.dart file and rerun the generate_code.dart and generate_readme.dart files.

License

This work is licensed under the MIT license. The data used from the Unicode CLDR is licensed under the Unicode v3 license.

SPDX-License-Identifier: MIT AND Unicode-3.0