{"id":32305804,"url":"https://github.com/playx-flutter/playx_localization","last_synced_at":"2025-10-23T06:56:12.434Z","repository":{"id":183352445,"uuid":"669813347","full_name":"playx-flutter/playx_localization","owner":"playx-flutter","description":"Easily manage and update app localization with a simple implementation and a lot of utilities.","archived":false,"fork":false,"pushed_at":"2025-07-01T12:29:45.000Z","size":399,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-23T06:55:59.340Z","etag":null,"topics":["flutter","flutter-package","flutterlocalization","localization"],"latest_commit_sha":null,"homepage":"","language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/playx-flutter.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-07-23T14:10:36.000Z","updated_at":"2025-07-01T12:29:49.000Z","dependencies_parsed_at":"2023-07-24T05:23:05.901Z","dependency_job_id":"ef355f0c-1323-47c3-9621-bd51e37449d7","html_url":"https://github.com/playx-flutter/playx_localization","commit_stats":null,"previous_names":["playx-flutter/playx_localization"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/playx-flutter/playx_localization","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/playx-flutter%2Fplayx_localization","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/playx-flutter%2Fplayx_localization/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/playx-flutter%2Fplayx_localization/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/playx-flutter%2Fplayx_localization/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/playx-flutter","download_url":"https://codeload.github.com/playx-flutter/playx_localization/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/playx-flutter%2Fplayx_localization/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280577131,"owners_count":26354072,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-23T02:00:06.710Z","response_time":142,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["flutter","flutter-package","flutterlocalization","localization"],"created_at":"2025-10-23T06:56:07.513Z","updated_at":"2025-10-23T06:56:12.424Z","avatar_url":"https://github.com/playx-flutter.png","language":"Dart","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Playx Localization\n\n[![pub package](https://img.shields.io/pub/v/playx_localization.svg?color=1284C5)](https://pub.dev/packages/playx_localization)\n\n\nSimplify app localization management with Playx Localization. This package offers a straightforward implementation and a wealth of utilities to manage and update app localization effortlessly.\n\n## Features 🔥\n\n-   **Easy Locale Management:** Create and manage app locales with the ability to easily switch between them.\n-   **Context-Free Localization:** No need for `BuildContext` anymore, making localization even simpler.\n-   **Dart Isolate Support:** Supports Dart isolates for background localization tasks.\n-   **Multiple File Formats:** Load translations from JSON, CSV, Yaml, XML, and more.\n-   **React to Locale Changes:** Automatically react to and persist locale changes within the app.\n-   **Advanced Localization:** Supports plural, gender, nesting, RTL locales, and more.\n-   **Fallback Locale Handling:** Define fallback locale keys for seamless localization fallbacks.\n\n## Installation\nIntegrating **Playx Localization** into your Flutter project is straightforward. Follow these steps:\n\n### Add Dependency\nInclude the following line in your `pubspec.yaml` file under the `dependencies` section:\n\n```yaml  \nplayx_localization: ^0.1.0  \n``` \n\n### Add Translation Files\nOrganize your localization files within a `translations` folder under the `assets` directory. The files should follow a specific naming convention:\n\n```plaintext  \nassets  \n└── translations  \n    ├── {languageCode}.{ext}                  \n    └── {languageCode}-{countryCode}.{ext}    \n```  \n\nFor example:\n\n```plaintext  \nassets  \n└── translations  \n    ├── en.json  \n    └── en-US.json   \n```  \n\n### Declare Assets Localization\nDeclare the localization directory in your `pubspec.yaml`:\n\n```yaml  \nflutter:  \n  assets:  \n    - assets/translations/  \n```\n\n### Loading Translations from Other Resources\n**Playx Localization** supports loading translations from various sources such as JSON, CSV, HTTP, XML, YAML files, etc. For more information, refer to [Easy Localization Loader](https://github.com/aissat/easy_localization_loader).\n\n### Note on iOS\nTo enable translation on iOS devices, add supported locales to `ios/Runner/Info.plist` as described [here](https://flutter.dev/docs/development/accessibility-and-localization/internationalization#specifying-supportedlocales).\n\n## Usage\nUtilizing **Playx Localization** in your app involves a few simple steps:\n\n### 🔥Boot Core\nInitialize the Playx core package with your desired locale configuration:\n\n```dart    \nvoid main() async {    \n\tWidgetsFlutterBinding.ensureInitialized();\n  \n  // Define your supported locales and other configurations\n\tconst locales = [  \n\t  XLocale(id: 'en', name: 'English', languageCode: 'en'),  \n\t  XLocale(id: 'ar', name: 'العربية', languageCode: 'ar'),  \n\t];  \n  \n\tfinal config = PlayxLocaleConfig(  \n\t  supportedLocales: locales,  \n\t  startLocale: locales.first,  \n\t  fallbackLocale: locales.first,  \n\t  useFallbackTranslations: true,  \n\t);\n\t // Boot Playx Localization with the defined configuration\n\t await PlayxLocalization.boot(config: config);\n\n\t runApp(const MyApp());\n}\n```\n\n### 🔥 Use `PlayxLocalizationBuilder` Widget\nWrap your `MaterialApp` or `CupertinoApp` with the `PlayxLocalizationBuilder` widget to listen to locale changes:\n\n```dart\nclass MyApp extends StatelessWidget {    \n  const MyApp({Key? key});    \n    \n  @override    \n  Widget build(BuildContext context) {  \n    return PlayxLocalizationBuilder(builder: (context, locale) {  \n      return MaterialApp(  \n        supportedLocales: PlayxLocalization.supportedLocales,  \n        localizationsDelegates: PlayxLocalization.localizationDelegates,  \n        locale: locale.locale,  \n        home: const MyHomePage(),  \n      );  \n    });  \n   }    \n }  \n```\n\n### 🔥 PlayxLocaleConfig Properties\nConfigure your localization preferences using the `PlayxLocaleConfig` properties:\n\n| Property                 | Required | Default                  | Description                                                                                                                                                                   |  \n| ------------------------ | -------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |  \n| supportedLocales         | true     |                          | List of supported locales.                                                                                                                                                    |  \n| path                     | false    | 'assets/translations'    | Path to the folder containing localization files.                                                                                                                                  |  \n| assetLoader              | false    | `RootBundleAssetLoader()`| Loader for localization files. You can use custom loaders or the default loader provided.                        |  \n| fallbackLocale           | false    |                          | The fallback locale used when the desired locale is not available in the supported locales list.                                                                                                   |  \n| startLocale              | false    |                          | The initial locale when the app starts. If null, it uses the device locale.                                                                                                                                                   |  \n| saveLocale               | false    | `true`                   | Save the chosen locale in the device's storage.                                                                                                                                                |  \n| useFallbackTranslations | false    | `true`                   | Use fallback translations if a localization key is not found in the locale file.                                                                                               |  \n| useOnlyLangCode          | false    | `false`                  | Use only language code for reading localization files.                                                                                                                         |  \n\n### Update App Locale\nSwitch between locales using the `PlayxLocalization` facade:\n\n```dart     \nFloatingActionButton.extended(  \n  onPressed: () {  \n    PlayxLocalization.updateByIndex(  \n      PlayxLocalization.isCurrentLocaleArabic() ? 0 : 1\n    );  \n  },  \n  label: Text('change_language'.tr),  \n  icon: const Icon(Icons.update),  \n)  \n```   \n\n\n### 🔥 Translate `tr()`\n\n#### The package uses [`Easy Localization`](https://pub.dev/packages/easy_localization) under the hood to manage translations and Plurals as below.\n\nRetrieve localized text using:\n\n-   `'text'.tr(context: context)`\n-   `context.tr()`\n-   `Text('text').tr(context: context)`\n\n```dart\nText('title').tr(context:context) //Text widget  \n  \nprint('title'.tr(context:context)); //String  \n\nvar title = tr('title',context:context) // Static function  \n  \nText(context.tr('title')) //Extension on BuildContext` \n```\n\nProviding context to the `tr` function ensures widgets are rebuilt correctly when the locale changes.  \nFor classes without context, you can still use the `tr` function without context, though note that widgets will not rebuild on locale changes when used this way, But there is an option to force app update on locale change.\n\n#### Arguments:\nPass arguments to the `tr()` function for dynamic translations:\n\n| Name      | Type                | Description                                                                         |  \n| --------- | ------------------- | ----------------------------------------------------------------------------------- |  \n| args      | `List\u003cString\u003e`      | List of localized strings. Replaces `{}` left to right                              |  \n| namedArgs | `Map\u003cString, String\u003e` | Map of localized strings. Replaces the name keys `{key_name}` according to its name |  \n| gender    | `String`            | Gender switcher. Changes the localized string based on gender string                |  \n\nExample:\n\n```json  \n{  \n   \"msg\": \"{} are written in the {} language\",  \n   \"msg_named\": \"Playx localization is written in the {lang} language\",  \n   \"msg_mixed\": \"{} are written in the {lang} language\",  \n   \"gender\": {  \n      \"male\": \"Hi man ;) {}\",  \n      \"female\": \"Hello girl :) {}\",  \n      \"other\": \"Hello {}\"  \n   }  \n}  \n```  \nUse it like this:\n\n```dart  \n// args  \nText('msg').tr(args: ['Playx localization', 'Dart']),  \n  \n// namedArgs  \nText('msg_named').tr(namedArgs: {'lang': 'Dart'}),  \n  \n// args and namedArgs  \nText('msg_mixed').tr(args: ['Playx localization'], namedArgs: {'lang': 'Dart'}),  \n  \n// gender  \nText('gender').tr(gender: _gender ? \"female\" : \"male\"),  \n  \n```\n\n### 🔥 Plurals `plural()`\n\nYou can translate with pluralization.  \nTo insert a number in the translated string, use `{}`. Number formatting supported, for more information read [NumberFormat](https://pub.dev/documentation/intl/latest/intl/NumberFormat-class.html) class documentation.\n\nYou can use extension methods of [String] or [Text] widget, you can also use `plural()` as a static function.\n\n#### Arguments:\n\n| Name      | Type                  | Description                                                                                                                  |  \n| --------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------- |  \n| value     | `num` | Number value for pluralization                                                                                               |  \n| args      | `List\u003cString\u003e` | List of localized strings. Replaces `{}` left to right                                                                       |  \n| namedArgs | `Map\u003cString, String\u003e` | Map of localized strings. Replaces the name keys `{key_name}` according to its name                                          |  \n| name      | `String` | Name of number value. Replaces `{$name}` to value                                                                            |  \n| format    | `NumberFormat` | Formats a numeric value using a [NumberFormat](https://pub.dev/documentation/intl/latest/intl/NumberFormat-class.html) class |  \n\nExample:\n\n``` json{  \n  \"day\": {  \n    \"zero\":\"{} дней\",  \n    \"one\": \"{} день\",  \n    \"two\": \"{} дня\",  \n    \"few\": \"{} дня\",  \n    \"many\": \"{} дней\",  \n    \"other\": \"{} дней\"  \n  },  \n  \"money\": {  \n    \"zero\": \"You not have money\",  \n    \"one\": \"You have {} dollar\",  \n    \"many\": \"You have {} dollars\",  \n    \"other\": \"You have {} dollars\"  \n  },  \n  \"money_args\": {  \n    \"zero\": \"{} has no money\",  \n    \"one\": \"{} has {} dollar\",  \n    \"many\": \"{} has {} dollars\",  \n    \"other\": \"{} has {} dollars\"  \n  },  \n  \"money_named_args\": {  \n    \"zero\": \"{name} has no money\",  \n    \"one\": \"{name} has {money} dollar\",  \n    \"many\": \"{name} has {money} dollars\",  \n    \"other\": \"{name} has {money} dollars\"  \n  }  \n}  \n```  \n⚠️ Key \"other\" required!\n\n```dart  \n//Text widget with format  \nText('money').plural(1000000, format: NumberFormat.compact(locale: context.locale.toString())) // output: You have 1M dollars  \n  \n//String  \nprint('day'.plural(21)); // output: 21 день  \n  \n//Static function  \nvar money = plural('money', 10.23) // output: You have 10.23 dollars  \n  \n//Text widget with plural BuildContext extension  \nText(context.plural('money', 10.23))  \n  \n//Static function with arguments  \nvar money = plural('money_args', 10.23, args: ['John', '10.23'])  // output: John has 10.23 dollars  \n  \n//Static function with named arguments  \nvar money = plural('money_named_args', 10.23, namedArgs: {'name': 'Jane', 'money': '10.23'})  // output: Jane has 10.23 dollars  \nvar money = plural('money_named_args', 10.23, namedArgs: {'name': 'Jane'}, name: 'money')  // output: Jane has 10.23 dollars  \n```  \n\n### 🔥 Linked translations:\n\nIf there's a translation key that will always have the same concrete text as another one you can just link to it. To link to another translation key, all you have to do is to prefix its contents with an `@:` sign followed by the full name of the translation key including the namespace you want to link to.\n\nExample:\n```json  \n{  \n  \"example\": {  \n  \"hello\": \"Hello\",  \n    \"world\": \"World!\",  \n    \"helloWorld\": \"@:example.hello @:example.world\"  \n  }  \n}  \n```  \n\n```dart  \nprint('example.helloWorld'.tr); //Output: Hello World!  \n```  \n\nYou can also do nested anonymous and named arguments inside the linked messages.\n\nExample:\n\n```json  \n{  \n  \"date\": \"{currentDate}.\",  \n  \"dateLogging\": \"INFO: the date today is @:date\"  \n}  \n```  \n```dart  \nprint(tr('dateLogging', namedArguments: {'currentDate': DateTime.now().toIso8601String()})); //Output: INFO: the date today is 2020-11-27T16:40:42.657.  \n```  \n\n#### Formatting linked translations:\n\nFormatting linked locale messages  \nIf the language distinguishes cases of character, you may need to control the case of the linked locale messages. Linked messages can be formatted with modifier `@.modifier:key`\n\nThe below modifiers are available currently.\n\n- `upper`: Uppercase all characters in the linked message.\n- `lower`: Lowercase all characters in the linked message.\n- `capitalize`: Capitalize the first character in the linked message.\n\nExample:\n\n```json  \n{  \n  \"example\": {  \n  \"fullName\": \"Full Name\",  \n    \"emptyNameError\": \"Please fill in your @.lower:example.fullName\"  \n  }  \n}  \n```  \n\nOutput:\n\n```dart  \nprint('example.emptyNameError'.tr); //Output: Please fill in your full name  \n```  \n\n### 🔥 Get device locale `deviceLocale`\n\nGet device locale\n\nExample:\n\n```dart  \nprint(${PlayxLocalization.deviceLocale.toString()}) // OUTPUT: en_US  \n```  \n\n### 🔥 Delete save locale `deleteSaveLocale()`\n\nClears a saved locale from device storage\n\nExample:\n\n```dart  \nRaisedButton(  \n  onPressed: (){  \n    PlayxLocalization.deleteSaveLocale();  \n  },  \n  child: Text(LocaleKeys.reset_locale).tr(),  \n)  \n```  \n\n\n### 🔥``PlayxLocalization`` available methods :\n\n| Method           | Description                                                |  \n| -----------      | :--------------------------------------------------------  |  \n| currentIndex     | Get current `XLocale` index.                                |  \n| currentXLocale   | Get current `XLocale`.                                      |   \n| currentLocale    | Get current locale.                                    |  \n| deviceLocale     | Get current device locale.                                      |  \n| nextLocale       | updates the app locale to the next locale .                   |  \n| updateByIndex    | updates the app locale by the index.                        |  \n| updateById       | updates the app locale by the `XLocale` id.                        |  \n| updateTo         | updates the app locale to a specific `XLocale`.              |  \n| updateToDeviceLocale | Updates the app locale to current device locale.              |  \n| updateByLanguageCode | updates the app locale by language code and country code if available              |  \n| supportedXLocales| Get current supported x locales configured in `XLocaleConfig `. |  \n| supportedLocales| Get current supported locales of `supportedXLocales`.                         |  \n| isCurrentLocaleArabic| Check if current locale is arabic.                         |                       |  \n| isCurrentLocaleEnglish| Check if current locale is english.                        |  \n| isCurrentLocaleRtl| Check if current locale is rtl.                         |  \n| currentLocaleToString| Convert current [locale] to String with custom [separator] representing language.    \n| deleteSavedLocale| Deletes saved locale from device storage.                         |  \n\n\n### 🔥 Extensions \u0026 utilities\n\nThe package include other extensions and utitlies that can be helpful for development.\n\nFor Example:\n\n#### Convert Date to formated and localized String using:\n\n```dart  \n  final dateText = DateTime.now().toFormattedDate(  \n      format: 'yyyy-MM-dd',  \n      locale: PlayxLocalization.currentLocale.toStringWithSeparator());  \n  \n  print('Curent date: $dateText');  \n```  \n\n#### There is also other extensions on nubmer\n| Method           | Description                                                |  \n| -----------      | :--------------------------------------------------------  |  \n| roundToPrecision     | Extension function to round number to certain number.   |  \n| toFormattedCurrencyNumber   | Extension function to format number to currency number.     |   \n| toFormattedNumber    | Extension function to format number to  String.           |  \n\n\n\n\n## Documentation \u0026\u0026 References\n\n- [Easy Localization](https://pub.dev/packages/easy_localization), The app uses the easy localization package under the hood to load translations.\n- [Documentaion](https://pub.dev/packages/playx_localization#documentation--references)\n\n\n## See Also:\n[Playx](https://pub.dev/packages/playx) : Playx eco system helps with redundant features , less code , more productivity , better organizing.\n\n[playx_core](https://pub.dev/packages/playx_core) : core package of playx.\n\n[playx_theme](https://pub.dev/packages/playx_theme) : Multi theme features for flutter apps from playx eco system.\n\n[playx_widget](https://pub.dev/packages/playx_widget) : PlayX widget package for playx eco system that provide custom utility widgets to make development faster.\n\n[playx_version_update](https://pub.dev/packages/playx_version_update) : Easily show material update dialog in Android or Cupertino dialog in IOS with support for Google play in app updates.\n\n[playx_network](https://pub.dev/packages/playx_network) :  Wrapper around Dio that can perform api request with better error handling and easily get the result of any api request.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplayx-flutter%2Fplayx_localization","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fplayx-flutter%2Fplayx_localization","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplayx-flutter%2Fplayx_localization/lists"}