flutter_pipwave_localization 0.2.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.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