# flutter_i18n 0.13.2 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.13.2' ``` Published: 2020-04-24T20:07:25.746303Z Expected archive SHA-256: fb23273aa9e341aa9f70085791466f3ae2eeda0b1005364512d25199436f6aea Available in cache; verification: upstream_checksum ## Direct dependencies - flutter: map[sdk:flutter] - flutter_localizations: map[sdk:flutter] - intl: ^0.16.0 - yaml: ^2.2.0 ## Package README (untrusted upstream documentation) # flutter_i18n 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) ------------------------------------------------ ## 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 or YAML format | | `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...)), GlobalMaterialLocalizations.delegate, GlobalWidgetsLocalizations.delegate ], ``` 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. If there isn't any translation available for the required key, 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). ## 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.