Skip to main content

playx_localization 1.0.0 copy "playx_localization: ^1.0.0" to clipboard
playx_localization: ^1.0.0 copied to clipboard

Easily manage and update app localization with a simple implementation and a lot of utilities.

Playx Localization #

pub package Build codecov Docs

Manage the locales of your Flutter app, translate text without a BuildContext, handle plurals the way each language needs them, and remember the user's choice.

Documentation: https://playx-flutter.github.io/playx_localization/

Features #

  • Locale management: switch by index, id, language code or XLocale, follow the device language, reset.
  • Translate anywhere: 'title'.tr() works in widgets, view models and plain Dart classes.
  • Real plurals: Arabic مركبة / مركبتان / ٣ مركبات / ١١ مركبة from one entry, plus Russian, Polish and more. Optional Arabic digits.
  • Persistence: the selected locale is saved by id and restored, in the storage you choose.
  • Fallbacks: fallback locale, base-language files (en-US → en), optional fallback for empty values.
  • Flexible sources: JSON with nesting and linked files, merged loaders, your own loader, and translations shipped by other packages.
  • Per-call locale: show one string in English while the app is in Arabic, or skip translation with translate: false.
  • Command line tools: generate typed key constants and validate every locale in CI.
  • Locale utilities: Arabic/English text helpers, number, currency and date formatting, RTL detection.

Installation #

dependencies:
  playx_localization: ^1.0.0

Requires Dart 3.12 and Flutter 3.44 or newer.

Quick start #

1. Add a JSON file per locale and declare the folder in pubspec.yaml:

assets/translations
├── en.json     { "welcome": "Welcome, {name}!", "item": { "one": "{} item", "other": "{} items" } }
└── ar.json
flutter:
  assets:
    - assets/translations/

2. Boot it before runApp:

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  const locales = [
    XLocale(id: 'en', name: 'English', languageCode: 'en'),
    XLocale(id: 'ar', name: 'العربية', languageCode: 'ar'),
  ];

  await PlayxLocalization.boot(
    config: PlayxLocaleConfig(
      supportedLocales: locales,
      startLocale: locales.first,
      fallbackLocale: locales.first,
    ),
  );

  runApp(const MyApp());
}

3. Wrap your app:

PlayxLocalizationBuilder(
  builder: (context, xLocale) => MaterialApp(
    locale: xLocale.locale,
    supportedLocales: PlayxLocalization.supportedLocales,
    localizationDelegates: PlayxLocalization.localizationDelegates,
    home: const HomePage(),
  ),
)

4. Translate and switch:

Text('welcome'.tr(context: context, namedArgs: {'name': 'Sam'}));
Text(context.plural('item', 3));          // 3 items

await PlayxLocalization.updateById('ar'); // saved and restored on the next start

For iOS, also list the supported languages in ios/Runner/Info.plist, see the Flutter docs.

Highlights #

Nouns with numbers #

"vehicle": {
  "one": "مركبة",
  "two": "مركبتان",
  "few": "{} مركبات",
  "many": "{} مركبة",
  "other": "{} مركبة"
}
'vehicle'.plural(1);                          // مركبة
'vehicle'.plural(2);                          // مركبتان
'vehicle'.plural(3, localizeDigits: true);    // ٣ مركبات
'vehicle'.plural(11, localizeDigits: true);   // ١١ مركبة

A different locale for one key #

'title'.tr(locale: const Locale('en'));
await PlayxLocalization.preloadLocales([const Locale('en')]); // load it once

Translations from other packages #

await PlayxLocalization.registerTranslations(
  PlayxTranslationSource.package(package: 'my_package', namespace: 'my_package'),
);

Typed keys and validation #

dart run playx_localization:generate   # AppTrans.homeTitle.tr()
dart run playx_localization:validate   # missing keys, placeholders, plural forms

Guides #

Guide What it covers
Getting started Install, boot and the first translated screen.
Translation files File names, nesting, linked files, fallbacks, custom loaders.
Translating text tr, arguments, gender, links, a different locale for one key.
Plurals Plural forms per language, nouns with numbers, Arabic digits.
Switching locales Updating, following the device, resetting.
Persistence What is saved, custom storage, migration.
Translations from packages Let other packages register their own translations.
Command line tools Generate keys and validate translations.
Configuration Every PlayxLocaleConfig option.
Extensions String, number, date and locale helpers.
Testing Testing code that uses translations.
Migration Moving from 0.x to 1.0.

The full API reference is generated from the code.

Example #

A runnable app is in example/.

Contributing #

Issues and pull requests are welcome at github.com/playx-flutter/playx_localization. Before opening a pull request run:

dart format .
flutter analyze
flutter test --coverage

See the changelog for what changed in each release.

License #

See LICENSE.

1
likes
160
points
798
downloads

Documentation

Documentation
API reference

Publisher

verified publisherplayx.sourcya.io

Weekly Downloads

Easily manage and update app localization with a simple implementation and a lot of utilities.

Homepage
Repository (GitHub)
View/report issues

Topics

#playx #localization #translation #i18n

License

MIT (license)

Dependencies

flutter, flutter_localizations, intl, playx_core, shared_preferences_platform_interface

More

Packages that depend on playx_localization