PWLocalizationService class
A service that handles localization with ICU formatting support and dynamic language file downloading capabilities.
PWLocalizationService is the core service responsible for managing translations, ICU message formatting, and dynamic language file downloads. It provides a singleton instance that can be accessed throughout the application.
The service supports:
- Asset-based translation files for offline scenarios
- Dynamic downloading of translation files from remote servers
- Full ICU message formatting (plurals, gender, select)
- Nested translation key support
- Automatic fallback mechanisms
Example usage:
Initialize the service
await PWLocalizationService.instance.initialize(
assetPath: 'assets/translations',
downloadedPath: 'translations',
defaultLanguage: 'en',
locale: const Locale('en'),
);
Translate a key
String text = PWLocalizationService.instance.tr(
'welcome.message',
args: {'name': 'John'},
);
Download language files
await PWLocalizationService.instance.downloadLanguageFiles(
'https://api.example.com/translations',
['en', 'es', 'fr'],
);
- Inheritance
-
- Object
- ChangeNotifier
- PWLocalizationService
Properties
- assetPath → String
-
The configured asset path used during initialization (e.g.
assets/i18n).no setter - currentLocale → Locale?
-
Gets the current locale being used by the service.
no setter
- currentLocaleTag → String?
-
The current locale tag (lowercased BCP-47) if initialized.
no setter
- defaultLocaleTag → String
-
The configured fallback locale tag (lowercased BCP-47, e.g.
en,zh-CN).no setter - downloadedPath → String
-
The configured download subdirectory used during initialization.
no setter
- hashCode → int
-
The hash code for this object.
no setterinherited
- hasListeners → bool
-
Whether any listeners are currently registered.
no setterinherited
- isInitialized → bool
-
Returns whether the service has successfully initialized at least once.
no setter
- runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
-
supportedLocales
→ List<
Locale> -
Gets the list of locales for which translations are currently loaded.
no setter
Methods
-
addListener(
VoidCallback listener) → void -
Register a closure to be called when the object changes.
inherited
-
clearDownloadedTranslations(
) → Future< void> - Clears all downloaded translation files and cached data.
-
dispose(
) → void -
Discards any resources used by the object. After this is called, the
object is not in a usable state and should be discarded (calls to
addListener will throw after the object is disposed).
inherited
-
downloadLanguageFiles(
String baseUrl, List< String> languageCodes, {Map<String, String> ? headers, Map<String, dynamic> ? queryParameters}) → Future<void> - Downloads the latest language files from a remote URL for dynamic updates.
-
downloadLanguageFilesForLocales(
String baseUrl, List< Locale> locales, {Map<String, String> ? headers, Map<String, dynamic> ? queryParameters}) → Future<void> - Downloads language files for a list of Locales.
-
downloadLanguageFilesForTags(
String baseUrl, List< String> localeTags, {Map<String, String> ? headers, Map<String, dynamic> ? queryParameters}) → Future<void> - Downloads language files using BCP-47 locale tags (preferred API).
-
gender(
String key, String gender, {Map< String, Object?> ? namedArgs, String? locale}) → String - Translates a key that has gender forms (male, female, other).
-
initialize(
{required String assetPath, required String downloadedPath, required String defaultLanguage, required Locale locale}) → Future< void> - Initializes the localization service with the specified configuration.
-
isLocaleSupported(
String languageCode) → bool - Checks if translations are available for the specified language code.
-
isLocaleSupportedLocale(
Locale locale) → bool - Checks if translations are available for the specified Locale.
-
isLocaleSupportedTag(
String tag) → bool - Checks if translations are available for the specified locale tag (BCP-47).
-
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
notifyListeners(
) → void -
Call all the registered listeners.
inherited
-
plural(
String key, num count, {Map< String, Object?> ? namedArgs, String? locale}) → String - Translates a key that has plural forms (zero, one, many, other).
-
removeListener(
VoidCallback listener) → void -
Remove a previously registered closure from the list of closures that are
notified when the object changes.
inherited
-
toString(
) → String -
A string representation of this object.
inherited
-
tr(
String key, {Object? args, Map< String, Object?> ? namedArgs, String? locale}) → String - Translates a key with optional ICU formatting and arguments.
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited
Static Properties
- instance → PWLocalizationService
-
no setter
- newInstance → PWLocalizationService
-
Returns a new instance of the localization service.
no setter
Static Methods
-
localeFromTag(
String tag) → Locale - Parses a BCP-47 tag string into a Locale object.
-
localeToTag(
Locale locale) → String - Converts a Locale to its BCP-47 string representation.
-
normalizeLocaleTag(
String tag) → String - Normalizes a BCP-47 locale tag by trimming whitespace.
-
tagToLanguageCode(
String tag) → String - Extracts the language code from a BCP-47 tag (e.g. 'zh' from 'zh-CN').