i18n_multilanguage_with_flags #

Generic Flutter i18n toolkit with language metadata, flag dropdowns, and language selection persistence.

This package is designed to be reusable in any app:

• it does not force any predefined translation keys
• it does not require a specific architecture
• each developer provides their own translation map and UI labels

What You Get #

• LanguageMetadata model (language id, locale, flag code, translator code).
• defaultLanguageCatalog with ready-to-use language metadata.
• I18nMultilanguageController for language state and tr(key) lookup.
• LanguageFlagDropdown for language selector with country flags.
• I18nLanguageSelectionForm with native language, target language, and username.
• LanguageSelectionStorage with SharedPreferences support.

Install #

dependencies:
  i18n_multilanguage_with_flags: ^0.1.0

Then run:

flutter pub get

Quick Start #

import 'package:i18n_multilanguage_with_flags/i18n_multilanguage_with_flags.dart';

final controller = I18nMultilanguageController(
  languages: defaultLanguageCatalog,
  initialUiLanguageId: 'en_us',
  fallbackLanguageId: 'en_us',
  translations: const {
    'en_us': {
      'screen_title': 'Language Setup',
      'native_language': 'Native language',
      'target_language': 'Language to practice',
      'continue': 'Continue',
    },
    'pt_br': {
      'screen_title': 'Configuracao de Idioma',
      'native_language': 'Idioma nativo',
      'target_language': 'Idioma para praticar',
      'continue': 'Continuar',
    },
  },
);

final title = controller.tr('screen_title');

Implementation Guide #

1. Define your translation keys #

Use any key format you prefer (snake_case, dot.notation, etc.).

const appTranslations = <String, Map<String, String>>{
  'en_us': {
    'home.title': 'Welcome',
    'home.subtitle': 'Pick your language',
  },
  'es_es': {
    'home.title': 'Bienvenido',
    'home.subtitle': 'Elige tu idioma',
  },
};

2. Create your language catalog #

Use defaultLanguageCatalog or your own list.

final catalog = defaultLanguageCatalog;

Configurable catalog (filter/add/override):

final catalog = buildConfigurableLanguageCatalog(
  includeIds: const ['en_us', 'pt_br', 'es_es'],
  excludeIds: const ['es_es'],
  addOrOverride: const [
    LanguageMetadata(
      id: 'eo_intl',
      name: 'Esperanto',
      englishName: 'Esperanto',
      flagCode: 'us',
      locale: 'eo-EO',
      translationCode: 'eo',
      shortCode: 'eo',
      voiceCode: 'eo',
    ),
  ],
);

Custom catalog example:

const catalog = <LanguageMetadata>[
  LanguageMetadata(
    id: 'en_us',
    name: 'English',
    englishName: 'English',
    flagCode: 'us',
    locale: 'en-US',
    translationCode: 'en',
    shortCode: 'en',
    voiceCode: 'en-US',
  ),
];

3. Initialize the controller #

final controller = I18nMultilanguageController(
  languages: catalog,
  translations: appTranslations,
  initialUiLanguageId: 'en_us',
  fallbackLanguageId: 'en_us',
);

4. Render text using your keys #

Text(controller.tr('home.title'))

5. Add language selector with flags #

LanguageFlagDropdown(
  languages: controller.languages,
  value: controller.uiLanguageId,
  labelText: controller.tr('native_language'),
  onChanged: (languageId) {
    if (languageId == null) return;
    controller.setUiLanguage(languageId);
  },
)

6. Persist user selection (optional) #

final storage = LanguageSelectionStorage();

await controller.loadFromStorage(storage);
await controller.saveToStorage(storage);

By default this persists:

• language
• target_language
• language_to_learn (legacy vector)
• username

Use custom keys:

final storage = LanguageSelectionStorage(
  keys: const I18nStorageKeys(
    uiLanguageKey: 'my_app.language',
    targetLanguageKey: 'my_app.target_language',
    targetLanguageLegacyVectorKey: 'my_app.language_vector',
    usernameKey: 'my_app.username',
  ),
);

7. Add or remove languages at runtime #

// Add or update one language
controller.upsertLanguage(
  const LanguageMetadata(
    id: 'it_it',
    name: 'Italiano',
    englishName: 'Italian',
    flagCode: 'it',
    locale: 'it-IT',
    translationCode: 'it',
    shortCode: 'it',
    voiceCode: 'it-IT',
  ),
);

// Remove one language (returns false if not found or catalog would become empty)
controller.removeLanguage('pt_br');

// Replace full catalog
controller.replaceLanguages(
  buildConfigurableLanguageCatalog(includeIds: const ['en_us', 'es_es']),
);

Language Selection Form #

Use I18nLanguageSelectionForm for a complete setup flow:

I18nLanguageSelectionForm(
  languages: controller.languages,
  initialUiLanguageId: controller.uiLanguageId,
  initialTargetLanguageId: controller.targetLanguageId,
  initialUsername: controller.username,
  uiLanguageLabel: controller.tr('native_language'),
  targetLanguageLabel: controller.tr('target_language'),
  usernameLabel: controller.tr('name'),
  usernameHint: controller.tr('name_hint'),
  submitLabel: controller.tr('continue'),
  onSubmit: (snapshot) async {
    controller.applySnapshot(snapshot);
    await controller.saveToStorage(storage);
  },
)

API Overview #

• I18nMultilanguageController
• LanguageMetadata
• LanguageSelectionSnapshot
• LanguageSelectionStorage
• I18nStorageKeys
• FlagIcon
• LanguageFlagDropdown
• I18nLanguageSelectionForm
• defaultLanguageCatalog
• buildDefaultLanguageCatalogMap()
• buildConfigurableLanguageCatalog(...)

Notes #

• tr(key) fallback order:
  1. selected language
  2. fallback language
  3. provided fallbackValue
  4. key itself
• Unknown language ids are safely ignored and fallback is used.
• You can replace translations at runtime using setTranslations(...).

Example App #

A runnable app is available in example/:

cd example
flutter pub get
flutter run