flutter_pipwave_localization 0.3.1

Powerful and flexible localization package for Pipwave Flutter projects, featuring ICU message formatting, runtime locale switching, asset and dynamic translation file support.

Changelog

0.3.1 27th Feb 2026

Enhanced

• Translation lookup fallback: When a locale is not found in downloaded translations, fall back to asset translations
• Empty map handling: Empty translation maps are treated as null and fall through the fallback chain (downloaded → asset → language-code variants)

0.3.0+1 27th Feb 2026

Documentation

• Updated README with Built-in Localization Delegates section (supported languages table, implementation guide, adding new delegates via generator)

0.3.0 27th Feb 2026

Added

• New localization delegates: Guarani (gn), Hausa (ha), Hawaiian (haw), Igbo (ig), Javanese (jv), Latin (la), Maori (mi), Nahuatl (nah), Quechua (qu), Shona (sn), Somali (so), Swahili (sw), Tajik (tg), Turkmen (tk), Xhosa (xh), Yoruba (yo), Cantonese (yue)
• Delegate generator tool: tool/create_delegate.dart reads a JSON file and generates Material, Cupertino, and Widget localization delegate files
• Sample delegate JSON: tool/sample_delegate.json (Swahili) as a template for creating new language delegates
• Auto-registration: The generator script automatically updates delegates.dart with imports/exports and registry entries

Enhanced

• Corrected translations across delegate files (removed incorrectly copied Tajik/other-language strings, restored native translations per language)

0.2.1 25th Feb 2026

Enhanced

• plural() and gender() now fall back to tr() when the key does not map to a plural or gender object, allowing mixed keys (e.g. simple strings or ICU-inline format) to be resolved via tr instead of returning the raw key

0.2.0 25th Feb 2026

BREAKING CHANGES

• Rename translate to tr, translatePlural to plural, translateGender to gender
• tr no longer handles plural or gender object maps. Use plural() and gender() instead

Migration

Old API	New API
service.translate(key, args: {...})	service.tr(key, args: {...})
service.translate(key, args: {'count': 5}) for object-based plurals	service.plural(key, 5)
service.translate(key, args: {'gender': 'male', ...}) for object-based gender	service.gender(key, 'male', namedArgs: {...})
context.tr('items.count', args: {'count': 5}) for object-based plurals	context.plural('items.count', 5)
context.tr('welcome', args: {'gender': 'male', ...}) for object-based gender	context.gender('welcome', 'male', namedArgs: {...})

ICU inline format (e.g. {count, plural, =0{...} other{...}} in the string value) still uses tr().

Added

• context.plural(key, count) and context.gender(key, gender) in the context extension
• plural() and gender() methods on PWLocalizationService
• String extensions: 'key'.trPlural(count) and 'key'.trGender(gender)

Enhanced

• Added documentation for previously undocumented methods (normalizeLocaleTag, localeToTag, tagToLanguageCode, localeFromTag, and internal helpers)
• Separated plural and gender logic into dedicated methods; tr handles only simple and ICU-inline translations

0.1.0 24th Feb 2026

BREAKING CHANGES

• Rename LocalizationProvider to PWLocalizationProvider
• Rename LocalizationService to PWLocalizationService
• Rename CustomLocalizationDelegate to PWLocalizationDelegate
• Rename LocalizedMaterialApp to PWLocalizedMaterialApp

Migration

Update your code as follows:

Old Name	New Name
LocalizationProvider	PWLocalizationProvider
LocalizationService	PWLocalizationService
CustomLocalizationDelegate	PWLocalizationDelegate
LocalizedMaterialApp	PWLocalizedMaterialApp

Feature

Add newInstance method to PWLocalizationService for creating new instances

0.0.4+1 12nd Feb 2026

Documentation

• Updated README on Code Generation

0.0.4 12nd Feb 2026

Feature

• Allow user to pass headers or query params when download language file

Enhancement

• Delete downloaded file if existed

0.0.3+2 11st Feb 2026

Enhancement

• Update BCP-47 locale tags to use proper casing for zh-CN in documentation and code comments

0.0.2 28th Jan 2026

Enhancement

• Support BCP-47 language code and rebuild layout after download assets

0.0.1+3 16th Jan 2026

Enhancement

• Add plural/gender detection and support positional/named args in translations.
• Implement plural and gender leaf node detection in key extraction.
• Mixture handling on named and unamed param.
• Validation on ICU formatting with better argument handling and fallback logic.

0.0.1+2 3rd Nov 2025

Documentation

• Updated README to document ICU message format plural support ("{count, plural, =0{message0} =1{message1} =2{message2} few{messageFew} many{messageMany} other{messageOther}}")

Enhancement

• Added code generation command documentation with default arguments
• Clarified support for both object-based and ICU message format plurals

0.0.1+1 21st Oct 2025

Fixed

• Export flutter_localizations

Enhancement

• Add getter to get delegates

0.0.1 21st Dec 2024

Added

• Initial release of PW Localization Flutter package

• Core Features:

  • EasyLocalization-compatible API for seamless migration
  • Full ICU message formatting support (plurals, gender, select)
  • Dynamic language file downloading from remote servers
  • Asset-based fallback for offline scenarios
  • Runtime locale switching capabilities
  • Type-safe translation key generation

• Widgets & Components:

  • LocalizationProvider - Main widget for app-wide localization
  • LocalizedMaterialApp - Convenience widget combining MaterialApp with localization
  • CustomLocalizationDelegate - Flutter localization system integration

• Services:

  • LocalizationService - Core service for translation management
  • ICU message formatting with intl package integration
  • Automatic fallback to asset files when downloads fail

• Extensions:

  • BuildContext extension for easy translation access (context.tr())
  • String extension for direct translation ('key'.tr())
  • Convenient argument passing with trArgs()

• Code Generation:

  • Translation key generator script (bin/generate.dart)
  • Automatic LocaleKeys class generation from JSON files
  • Type-safe translation key constants

• Advanced Features:

  • Nested translation key support (e.g., welcome.title)
  • Plural rule handling (zero, one, many, other)
  • Gender-based translations
  • Complex ICU message patterns
  • Translation caching and memory management
  • Download progress tracking and error recovery

Technical Details

• Dependencies: Flutter 3.8.0+, Dart 3.9.0+
• Key Packages: intl, dio, path_provider, flutter_localizations
• Architecture: Singleton service pattern with widget integration
• Storage: Asset-based with optional downloaded file caching
• Error Handling: Comprehensive exception handling with graceful fallbacks

Migration Guide

This package is designed as a drop-in replacement for EasyLocalization:

1. Replace EasyLocalization widget with LocalizationProvider
2. Update import statements to use flutter_pipwave_localization
3. Translation access patterns remain the same (context.tr())
4. Asset structure can remain unchanged
5. Optional: Use code generation for type-safe keys

Breaking Changes

• None in initial release (designed for seamless migration)

Known Issues

• ICU message formatting may have edge cases with complex nested structures
• Large translation files may impact initial load time
• Network-dependent features require proper error handling