# flutter_i18n 0.11.0

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.11.0'
```
Published: 2020-03-11T21:01:08.014565Z
Expected archive SHA-256: 575ab3688ee14f7704b83b697cd6ea22fe91a55dde7ecef8585f8db3f085f14d

Available in cache; verification: upstream_checksum
## Direct dependencies
- flutter: map[sdk:flutter]
- flutter_localizations: map[sdk:flutter]
- intl: ^0.16.1
- yaml: ^2.2.0

## Package README (untrusted upstream documentation)
# flutter_i18n
I18n made easy, for Flutter!

------------------------------------------------



## 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 | 
| 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 different 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
],
```

### `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", Text(""))
I18nText("your.key", Text(""), translationParams: {"user": "Flutter lover"})
I18nPlural("clicked.times", 2, 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<String, String>* 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.10.1]

Fix for #69

# [0.11.0]

New translation mechanism, with different and customizable loaders provided:

- FileTranslationLoader
- NetworkFileTranslationLoader
- E2EFileTranslationLoader