localize function

String localize(String key, ITranslations translations, { String? locale, })

To localize a translatable string, pass its key and the translations object.

The locale may also be passed, but if it's null the locale in I18n.localeStr will be used. If I18n.localeStr is not yet defined, it will use the default locale of the translation in I18n.defaultLocale.

Fallback order:

• If the translation to the exact locale is found, this will be returned.
• Otherwise, it tries to return a translation for the general language of the locale.
• Otherwise, it tries to return a translation for any locale with that language.
• Otherwise, it tries to return the key itself (which is the translation for the default locale).

Example 1: If "pt_br" is asked, and "pt_br" is available, return for "pt_br".

Example 2: If "pt_br" is asked, "pt_br" is not available, and "pt" is available, return for "pt".

Example 3: If "pt_mo" is asked, "pt_mo" and "pt" are not available, but "pt_br" is, return for "pt_br".

Implementation

String localize(
  String key,
  ITranslations translations, {
  String? locale,
}) {
  Map<String, String>? translatedStringPerLocale = translations[key];

  if (translatedStringPerLocale == null) {
    if (Translations.recordMissingKeys)
      Translations.missingKeys
          .add(TranslatedString(locale: translations.defaultLocaleStr, text: key));

    Translations.missingKeyCallback(key, translations.defaultLocaleStr);

    return key;
  }
  //
  else {
    locale = _effectiveLocale(locale);

    if (locale == "null")
      throw TranslationsException("Locale is the 4 letter string 'null', which is invalid.");

    // Get the translated string in the language we want.
    String? translatedString = translatedStringPerLocale[locale];

    // Return the translated string in the language we want.
    if (translatedString != null) return translatedString;

    // If there's no translated string in the locale, record it.
    if (Translations.recordMissingTranslations && locale != translations.defaultLocaleStr) {
      Translations.missingTranslations.add(TranslatedString(locale: locale, text: key));
      Translations.missingTranslationCallback(key, locale);
    }

    // ---

    var lang = _language(locale);

    // Try finding the translation in the general language. Note: If the locale
    // is already general, it was already searched, so no need to do it again.
    if (!_isGeneral(locale)) {
      translatedString = translatedStringPerLocale[lang];
      if (translatedString != null) return translatedString;
    }

    // Try finding the translation in any local with that language.
    for (MapEntry<String, String> entry in translatedStringPerLocale.entries) {
      if (lang == _language(entry.key)) return entry.value;
    }

    // If nothing is found, return the value or key,
    // that is the translation in the default locale.
    return translatedStringPerLocale[translations.defaultLocaleStr] ?? key;
  }
}