- π Easy translations for many languages
- π Load translations as JSON, CSV, Yaml, Xml using Easy Localization Loader
- πΎ React and persist to locale changes
- β‘ Supports plural, gender, nesting, RTL locales and more
βοΈ Error widget for missing translations- β€οΈ Extension methods on
Text
andBuildContext
- π» Code generation for localization files and keys.
- π Uses BLoC pattern
Add to your pubspec.yaml
:
dependencies:
easy_localization: <last_version>
Create folder and add translation files like this
assets
βββ translations
βββ {languageCode}.{ext} //only language code
βββ {languageCode}-{countryCode}.{ext} //or full locale code
Example:
assets
βββ translations
βββ en.json
βββ en-US.json
Declare your assets localization directory in pubspec.yaml
:
flutter:
assets:
- assets/translations/
You can use JSON,CSV,HTTP,XML,Yaml files, etc.
See Easy Localization Loader for more info.
For translation to work on iOS you need to add supported locales to
ios/Runner/Info.plist
as described here.
Example:
<key>CFBundleLocalizations</key>
<array>
<string>en</string>
<string>nb</string>
</array>
Add EasyLocalization widget like in example
import 'package:flutter/material.dart';
import 'package:flutter_localizations/flutter_localizations.dart';
import 'package:easy_localization/easy_localization.dart';
void main() {
runApp(
EasyLocalization(
supportedLocales: [Locale('en', 'US'), Locale('de', 'DE')],
path: 'assets/translations', // <-- change patch to your
fallbackLocale: Locale('en', 'US'),
child: MyApp()
),
);
}
class MyApp extends StatelessWidget {
@override
Widget build(BuildContext context) {
return MaterialApp(
localizationsDelegates: context.localizationDelegates,
supportedLocales: context.supportedLocales,
locale: context.locale,
home: MyHomePage()
);
}
}
Properties | Required | Default | Description |
---|---|---|---|
key | false | Widget key. | |
child | true | Place for your main page widget. | |
supportedLocales | true | List of supported locales. | |
path | true | Path to your folder with localization files. | |
assetLoader | false | RootBundleAssetLoader() |
Class loader for localization files. You can use custom loaders from Easy Localization Loader or create your own class. |
fallbackLocale | false | Returns the locale when the locale is not in the list supportedLocales . |
|
startLocale | false | Overrides device locale. | |
saveLocale | false | true |
Save locale in device storage. |
useOnlyLangCode | false | false |
Trigger for using only language code for reading localization files. Example: en.json //useOnlyLangCode: true en-US.json //useOnlyLangCode: false |
preloaderColor | false | Colors.white |
Background color for EmptyPreloaderWidget. If you use a different color background, change the color to avoid flickering |
preloaderWidget | false | EmptyPreloaderWidget() |
Shows your custom widget while translation is loading. |
Easy localization uses extension methods [BuildContext] for access to locale.
It's more easiest way change locale or get parameters π.
βΉοΈ No breaking changes, you can use old the static method EasyLocalization.of(context)
Example:
context.locale = Locale('en', 'US');
print(context.locale.toString());
Main function for translate your language keys
You can use extension methods of [String] or [Text] widget, you can also use tr()
as a static function.
Text('title').tr() //Text widget
print('title'.tr()); //String
var title = tr('title') //Static function
Name | Type | Description |
---|---|---|
context | BuildContext |
The location in the tree where this widget builds |
args | List<String> |
List of localized strings. Replaces {} left to right |
namedArgs | Map<String, String> |
Map of localized strings. Replaces the name keys {key_name} according to its name |
gender | String |
Gender switcher. Changes the localized string based on gender string |
Example:
{
"msg":"{} are written in the {} language",
"msg_named":"Easy localization are written in the {lang} language",
"msg_mixed":"{} are written in the {lang} language",
"gender":{
"male":"Hi man ;) {}",
"female":"Hello girl :) {}",
"other":"Hello {}"
}
}
// args
Text('msg').tr(args: ['Easy localization', 'Dart']),
// namedArgs
Text('msg_named').tr(namedArgs: {'lang': 'Dart'}),
// args and namedArgs
Text('msg_mixed').tr(args: ['Easy localization'], namedArgs: {'lang': 'Dart'}),
// gender
Text('gender').tr(gender: _gender ? "female" : "male"),
You can translate with pluralization.
To insert a number in the translated string, use {}
. Number formatting supported, for more information read NumberFormat class documentation.
You can use extension methods of [String] or [Text] widget, you can also use plural()
as a static function.
Name | Type | Description |
---|---|---|
context | BuildContext |
The location in the tree where this widget builds |
value | num |
Number value for pluralization |
format | NumberFormat |
Formats a numeric value using a NumberFormat class |
Example:
{
"day": {
"zero":"{} Π΄Π½Π΅ΠΉ",
"one": "{} Π΄Π΅Π½Ρ",
"two": "{} Π΄Π½Ρ",
"few": "{} Π΄Π½Ρ",
"many": "{} Π΄Π½Π΅ΠΉ",
"other": "{} Π΄Π½Π΅ΠΉ"
},
"money": {
"zero": "You not have money",
"one": "You have {} dollar",
"many": "You have {} dollars",
"other": "You have {} dollars"
}
}
//Text widget with format
Text('money').plural(1000000, format: NumberFormat.compact(locale: context.locale.toString())) // output: You have 1M dollars
//String
print('day'.plural(21)); // output: 21 Π΄Π΅Π½Ρ
//Static function
var money = plural('money', 10.23) // output: You have 10.23 dollars
Clears a saved locale from device storage
Example:
RaisedButton(
onPressed: (){
context.deleteSaveLocale();
},
child: Text(LocaleKeys.reset_locale).tr(),
)
At any time, you can take the main properties of the Easy localization widget using [BuildContext].
Are supported: supportedLocales, fallbackLocale, localizationDelegates.
Example:
print(context.supportedLocales); // output: [en_US, ar_DZ, de_DE, ru_RU]
print(context.fallbackLocale); // output: en_US
Code generation supports only json files, for more information run in terminal flutter pub run easy_localization:generate -h
Arguments | Short | Default | Description |
---|---|---|---|
--help | -h | Help info | |
--source-dir | -s | resources/langs | Folder containing localization files |
--output-dir | -O | lib/generated | Output folder stores for the generated file |
--output-file | -o | codegen_loader.g.dart | Output file name |
--format | -f | json | Support json or keys formats |
Steps:
- Open your terminal in the folder's path containing your project
- Run in terminal
flutter pub run easy_localization:generate
- Change asset loader and past import.
import 'generated/codegen_loader.g.dart';
...
void main(){
runApp(EasyLocalization(
child: MyApp(),
supportedLocales: [Locale('en', 'US'), Locale('ar', 'DZ')],
path: 'resources/langs',
assetLoader: CodegenLoader()
));
}
...
- All done!
If you have many localization keys and are confused, key generation will help you. The code editor will automatically prompt keys
Steps:
- Open your terminal in the folder's path containing your project
- Run in terminal
flutter pub run easy_localization:generate -f keys -o locale_keys.g.dart
- Past import.
import 'generated/locale_keys.g.dart';
- All done!
How to usage generated keys:
print(LocaleKeys.title.tr()); //String
//or
Text(LocaleKeys.title).tr(); //Widget
Arabic RTL | English LTR | Error widget |
---|---|---|
![]() |
![]() |
![]() |
We need your support. Projects like this can not be successful without support from the community. If you find this project useful, and would like to support further development and ongoing maintenance, please consider donating.