# flutter_i18n 0.19.3 i18n made easy for Flutter. With flutter_i18n you can make your app international, using just a simple .json file! ## Installing ``` export PUB_HOSTED_URL=https://pub.mirror.p-hatan.ir flutter pub add 'flutter_i18n:0.19.3' ``` Published: 2020-09-30T18:35:18.789660Z Expected archive SHA-256: 548e327f8446a697e9a37a9e722d7894224528ceba882448e54d08fe7cb56326 Available in cache; verification: upstream_checksum ## Direct dependencies - flutter: map[sdk:flutter] - flutter_localizations: map[sdk:flutter] - flutter_web_plugins: map[sdk:flutter] - intl: ^0.16.0 - merge_map: ^1.0.2 - universal_io: 1.0.1 - xml2json: ^4.2.0 - yaml: ^2.2.0 ## Package README (untrusted upstream documentation) # flutter_i18n [![All Contributors](https://img.shields.io/badge/all_contributors-3-orange.svg?style=flat-square)](#contributors-) I18n made easy, for Flutter! [![Pub Package](https://img.shields.io/pub/v/flutter_i18n.svg)](https://pub.dev/packages/flutter_i18n) [![GitHub Actions](https://github.com/ilteoood/flutter_i18n/workflows/Publish%20plugin/badge.svg)](https://github.com/ilteoood/flutter_i18n/actions) ------------------------------------------------ ## Table of contents * [Why you should use flutter_i18n?](#why-you-should-use-flutter_i18n) * [Loaders](#loaders) * [FileTranslationLoader](#filetranslationloader-configuration) * [NetworkFileTranslationLoader](#networkfiletranslationloader-configuration) * [NamespaceFileTranslationLoader](#namespacefiletranslationloader-configuration) * [E2EFileTranslationLoader](#e2efiletranslationloader-configuration) * [flutter_i18n in action](#flutter_i18n-in-action) * [Plugins](#plugins) * [Contributors](#contributors-) ## Why you should use flutter_i18n? The main goal of *flutter_i18n* is to simplify the i18n process in Flutter. I would like to recreate the same experience that you have with the Angular i18n: simple *json* files, one for each language that you want to support. ## Loaders Loader is a class which loads your translations from specific source. You can easy override loader and create your own. Available loaders: | Class name | Purpose | | --- | --- | | `FileTranslationLoader` | Loads translation files from JSON, YAML or XML format | | `LocalTranslationLoader` | Is a copy of `FileTranslationLoader`, but used to loads the files from the device storage instead of assets folder | | `NetworkFileTranslationLoader` | Loads translations from the remote resource | | `NamespaceFileTranslationLoader` | Loads translations from separate files | | `E2EFileTranslationLoader` | Special loader for solving isolates problem with flutter drive | ### `FileTranslationLoader` configuration To use this library, you must create a folder in your project's root: the `basePath`. Some examples: > /assets/flutter_i18n (the default one) > > /assets/i18n > > /assets/locales Inside this folder, you'll put the *json* or *yaml* files containing the translated keys. You have two options: - If you want to specify the country code > `basePath`/{languageCode}_{countryCode}.json - otherwise > `basePath`/{languageCode}.json If the *json* file is not available, we will look for a *yaml* file with the same name. In case both exist, the *json* file will be used. Of course, you must declare the subtree in your ***pubspec.yaml*** as assets: ```yaml flutter: assets: - {basePath} ``` The next step consist in the configuration of the *localizationsDelegates*; to use *flutter_i18n*, you should configure as follows: ```dart localizationsDelegates: [ FlutterI18nDelegate( translationLoader: FileTranslationLoader(...parameters...), missingTranslationHandler: (key, locale) { print("--- Missing Key: $key, languageCode: ${locale.languageCode}"); }, ), GlobalMaterialLocalizations.delegate, GlobalWidgetsLocalizations.delegate ], builder: FlutterI18n.rootAppBuilder() //If you want to support RTL. ``` Below you can find the name and description of the accepted parameters. The ***useCountryCode*** parameter depends on the *json* configuration: - if you used the pattern {languageCode}_{countryCode}, ***useCountryCode*** must be **true** - if you used the pattern {languageCode}, ***useCountryCode*** must be **false** The ***fallbackFile*** parameter was entroduces with the version **0.1.0** and provide a default language, used when the translation for the current running system is not provided. This should contain the name of a valid *json* file in *assets* folder. The ***basePath*** parameter is optionally used to set the base path for translations. If this option is not set, the default path will be `assets/flutter_i18n`. This path must be the same path as the one defined in your ***pubspec.yaml***. The ***forcedLocale*** parameter is optionally used to force a locale instead finding the system one. The ***decodeStrategies*** parameters is optionally used to choose witch kind of file you want to load. By default JSON, YAML and XML are enabled. If you use only one format, you can speed-up the bootstrap process using only the one you need. If there isn't any translation available for the required key, even in the fallback file, the same key is returned. ### `NetworkFileTranslationLoader` configuration Behaviour of this loader very similar as `FileTranslationLoader`. The main difference that we load translations from `NetworkAssetBundle` instead of `CachingAssetBundle`. Below you can find the name and description of the accepted parameters. The ***baseUri*** parameter provide base Uri for your remote translations. The ***useCountryCode*** parameter depends on the *json* configuration: - if you used the pattern {languageCode}_{countryCode}, ***useCountryCode*** must be **true** - if you used the pattern {languageCode}, ***useCountryCode*** must be **false** The ***fallbackFile*** parameter provide a default language, used when the translation for the current running system is not provided. The ***forcedLocale*** parameter is optionally used to force a locale instead finding the system one. For example if your translation files located at `https://example.com/static/en.json` you should configure as follows: ```dart localizationsDelegates: [ FlutterI18nDelegate(translationLoader: NetworkFileTranslationLoader(baseUri: Uri.https("example.com", "static")), GlobalMaterialLocalizations.delegate, GlobalWidgetsLocalizations.delegate ], ``` ### `NamespaceFileTranslationLoader` configuration Behaviour of this loader very similar as `FileTranslationLoader`. The main difference that we load translations from separate files per each language. For example `FileTranslationLoader` format: > /assets/flutter_i18n/en.json > > /assets/flutter_i18n/it.json `NamespaceFileTranslationLoader` format: > /assets/flutter_i18n/en/home_screen.json > > /assets/flutter_i18n/en/about_screen.json > > /assets/flutter_i18n/it/home_screen.json > > /assets/flutter_i18n/it/about_screen.json Example configuration: ```dart localizationsDelegates: [ FlutterI18nDelegate(translationLoader: NamespaceFileTranslationLoader(namespaces: ["home_screen", "about_screen"]), GlobalMaterialLocalizations.delegate, GlobalWidgetsLocalizations.delegate ], ``` Below you can find the name and description of the accepted parameters. The ***namespaces*** provide a list of filenames for the specific language directory. The ***useCountryCode*** parameter depends on the *json* configuration: - if you used the pattern {languageCode}_{countryCode}, ***useCountryCode*** must be **true** - if you used the pattern {languageCode}, ***useCountryCode*** must be **false** The ***fallbackDir*** provide a default language directory, used when the translation for the current running system is not provided. The ***basePath*** parameter is optionally used to set the base path for translations. If this option is not set, the default path will be `assets/flutter_i18n`. This path must be the same path as the one defined in your ***pubspec.yaml***. The ***forcedLocale*** parameter is optionally used to force a locale instead finding the system one. ### `E2EFileTranslationLoader` configuration The same as `FileTranslationLoader` configuration. This loader can be used for solving problem with flutter drive testing. It removes using separate isolate for loading translations (detailed issue described here: [issues/24703](https://github.com/flutter/flutter/issues/24703)). The ***useE2E*** parameter: - if you are in flutter drive testing mode – must be **true** - if you are in normal mode – must be **false**, in this case `FileTranslationLoader` will be used ## flutter_i18n in action After the configuration steps, the only thing to do is invoke the following method: ```dart FlutterI18n.translate(buildContext, "your.key") ``` Where: - *buildContext* is the *BuildContext* instance of the widget - *your.key* is the key to translate Other examples of use: Force a language to be loaded at run-time: ```dart await FlutterI18n.refresh(buildContext, languageCode, {countryCode}); ``` Plural translations: ```dart FlutterI18n.plural(buildContext, "your.key", pluralValue); ``` Text widget shorthand: ```dart I18nText("your.key", child: Text("")) I18nText("your.key", translationParams: {"user": "Flutter lover"}) I18nPlural("clicked.times", 1) I18nPlural("clicked.times", 2, child: Text("")) ``` For more informations and details, read the [CHANGELOG.md](CHANGELOG.md). Known problems: - In iOS simulator, is always used the *en_US* locale: see [here](https://github.com/ilteoood/flutter_i18n/issues/58). ## Plugins | Plugin | Description | |---------|-------------| | [flutter_i18n_locize](https://github.com/defint/flutter_i18n_locize) | Easy integration locize.io to flutter_i18n. | ## Contributors ✨ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):

Anton
🚇 ⚠️ 💻
Lucas Vienna
💻
jlcool
💻
Julian
💻 🤔
Andrey Gordeev
💻 🐛
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome! ## Changelog ## [0.2.0] *flutter_i18n* now manage strings that contain parameters; an example can be: "Hello, {user}!" For a correct translation, you must use the third parameter of the *translate* method, a *Map* where: - the keys are the placeholders used in the *.json* file (i.e. user) - the values are what you want to display ## [0.3.0] *flutter_i18n* now supports language change at runtime. To use it, you ***must*** invoke the method ```sh await FlutterI18n.refresh(buildContext, languageCode, {countryCode}); ``` ***NOTE***: *countryCode* is optional. ## [0.4.0] *flutter_i18n* now supports plurals. To use it, invoke the method: ```sh FlutterI18n.plural(buildContext, "your.key", pluralValue); ``` Where pluralValue is the integer value that will be used to determinate the plural form of the translation. Here is an example of configuration of the *.json* file: ```sh "clicked": { "times-0": "You clicked {times} times!", "times-1": "You clicked {time} time!", "times-2": "You clicked {times} times!" } ``` With this configuration, you must invoke the *plural* method as follow: ```sh FlutterI18n.plural(buildContext, "clicked.times", pluralValue); ``` FlutterI18n will choose the right key using the value of pluralValue: it will match the last key with a value <= of pluralValue. ## [0.5.0] *flutter_i18n* now supports the `basePath` configuration. The default one is: `assets/flutter_i18n`. To configure it, use the third optional parameter of `FlutterI18nDelegate`. ## [0.5.1] Print in log when a key is not found. ## [0.5.2] Fix for bug #10. ## [0.6.0] Exposed new method that return the locale used by the library, as requested in #16: ```sh FlutterI18n.currentLocale(); ``` ***NOTE***: the ***refresh*** method now accept a *Locale* as second parameter, instead of two strings. ***NOTE***: the constructor of *FlutterI18nDelegate* now accept only named parameter. ## [0.6.1] Fix for bug #22 ## [0.6.2] Fix for the delegate ## [0.6.3] Fix for #17 ## [0.6.4] Fix for #41 ## [0.7.0] Fix for #48 and implemented feature for #49. From this version of *FlutterI18n*, you can use as 4th parameter the ***forcedLanguage*** parameter, in order to avoid to call the *refresh* method on application startup. ## [0.8.0] Support for *yml* language files ## [0.8.1] Improved *json* and *yml* loading ## [0.8.2] Bugfix and code improvement ## [0.8.3] Library will print debug messages only in development mode ## [0.9.0] Added a new optional parameter to the translate method: *fallbackKey*. You can use it when the translation *key* is not found. ## [0.10.0] Added stateless widgets in order to avoid to deal with BuildContext. ```dart I18nText("your.key", Text("")) I18nText("your.key", Text(""), translationParams: {"user": "Flutter lover"}) I18nPlural("clicked.times", 2, Text("")) ``` ## [0.11.0] New translation mechanism, with different and customizable loaders provided: * FileTranslationLoader * NetworkFileTranslationLoader * E2EFileTranslationLoader ## [0.11.1] Plural translator improvements ## [0.12.0] New loader provided: ```NamespaceFileTranslationLoader``` ## [0.13.0] In the I18nText and I18nPlural widgets, the child parameter is now optional. The default value of the child parameter is now ```Text("")``` ## [0.13.1] Fix for #83. ## [0.13.2] Fixed immutable warnings. ## [0.14.0] New feature: file translation decode strategies. New translation strategy provided, able to load XML file. ## [0.15.0] New feature: missing key are now retrieved from the fallback file. ## [0.16.0] Full support for supportedLocales ## [0.16.1] Support for decode strategies on other loaders ## [0.16.2] Added missing translation handler, according to [issue/67](https://github.com/ilteoood/flutter_i18n/issues/67) ## [0.16.3] Removed cache parameter from loadString method, resolve [issue/116](https://github.com/ilteoood/flutter_i18n/issues/116) ## [0.17.0] RTL support. Test fix for [issue/115](https://github.com/ilteoood/flutter_i18n/issues/115) ## [0.18.0] New loader provided: * LocalTranslationLoader ## [0.19.0] Support for Flutter Web. Note: due to dart:io bug, NetworkFileTranslationLoader can't be used. ## [0.19.1] Removed useless parameter from LocalTranslationLoader and fixed delegate load method. ## [0.19.2] Plugins and better Flutter Web support. ## [0.19.3] Removed dart:io for better Flutter Web support.