- π Easy translations for many languages
- π Load translations as JSON, CSV, Yaml, Xml
- πΎ React and persist to locale changes
- β‘ Supports gender, nesting, RTL locales and more
- β©οΈ Fallback locale keys redirection
βοΈ Error widget for missing translations- β€οΈ Extension methods on
Text
andBuildContext
- π» Code generation for localization files and keys.
- π‘οΈ Null safety
- π¨οΈ Customizable logger.
Add to your pubspec.yaml
:
dependencies:
azbox-localization: <last_version>
Add Azbox widget like in example
import 'package:flutter/material.dart';
import 'package:flutter_localizations/flutter_localizations.dart';
import 'package:azbox/azbox.dart';
void main() async {
WidgetsFlutterBinding.ensureInitialized();
await Azbox.ensureInitialized();
runApp(
Azbox(
supportedLocales: [Locale('en', 'US'), Locale('de', 'DE')],
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. | |
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. |
useFallbackTranslations | false | false |
If a localization key is not found in the locale file, try to use the fallbackLocale file. |
useOnlyLangCode | false | false |
Trigger for using only language code for reading localization files. Example: en.json //useOnlyLangCode: true en-US.json //useOnlyLangCode: false |
errorWidget | false | FutureErrorWidget() |
Shows a custom error widget when an error occurs. |
Call Azbox.ensureInitialized()
in your main before runApp.
void main() async{
// ...
// Needs to be called so that we can await for Azbox.ensureInitialized();
WidgetsFlutterBinding.ensureInitialized();
await Azbox.ensureInitialized();
// ...
runApp(....)
// ...
}
Azbox localization uses extension methods [BuildContext] for access to locale.
It's the easiest way change locale or get parameters π.
βΉοΈ No breaking changes, you can use old the static method Azbox.of(context)
Example:
context.setLocale(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 translate()
as a static function.
Text('title').translate() //Text widget
print('title'.translate()); //String
var title = translate('title') //Static function
Text(context.translate('title')) //Extension on BuildContext
Name | Type | Description |
---|---|---|
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":"Azbox localization is 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').translate(args: ['Azbox localization', 'Dart']),
// namedArgs
Text('msg_named').translate(namedArgs: {'lang': 'Dart'}),
// args and namedArgs
Text('msg_mixed').translate(args: ['Azbox localization'], namedArgs: {'lang': 'Dart'}),
// gender
Text('gender').translate(gender: _gender ? "female" : "male"),
If 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.
Example:
{
...
"example": {
"hello": "Hello",
"world": "World!",
"helloWorld": "@:example.hello @:example.world"
}
...
}
print('example.helloWorld'.translate()); //Output: Hello World!
You can also do nested anonymous and named arguments inside the linked messages.
Example:
{
...
"date": "{currentDate}.",
"dateLogging": "INFO: the date today is @:date"
...
}
print('dateLogging'.translate(namedArguments: {'currentDate': DateTime.now().toIso8601String()})); //Output: INFO: the date today is 2020-11-27T16:40:42.657.
Formatting linked locale messages
If 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
The below modifiers are available currently.
upper
: Uppercase all characters in the linked message.lower
: Lowercase all characters in the linked message.capitalize
: Capitalize the first character in the linked message.
Example:
{
...
"example": {
"fullName": "Full Name",
"emptyNameError": "Please fill in your @.lower:example.fullName"
}
...
}
Output:
print('example.emptyNameError'.translate()); //Output: Please fill in your full name
Reset locale to device locale
Example:
RaisedButton(
onPressed: (){
context.resetLocale();
},
child: Text(LocaleKeys.reset_locale).translate(),
)
Get device locale
Example:
print(${context.deviceLocale.toString()}) // OUTPUT: en_US
Clears a saved locale from device storage
Example:
RaisedButton(
onPressed: (){
context.deleteSaveLocale();
},
child: Text(LocaleKeys.reset_locale).translate(),
)
At any time, you can take the main properties of the Azbox 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 azbox_localization:generate -h
Arguments | Short | Default | Description |
---|---|---|---|
--help | -h | Help info | |
--source-dir | -S | resources/langs | Folder containing localization files |
--source-file | -s | First file | File to use for localization |
--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 |
--[no-]skip-unnecessary-keys | -u | false | Ignores keys defining nested object except for pluarl(), gender() keywords. |
Steps:
- Open your terminal in the folder's path containing your project
- Run in terminal
flutter pub run azbox_localization:generate
- Change asset loader and past import.
import 'generated/codegen_loader.g.dart';
...
void main(){
runApp(Azbox(
child: MyApp(),
supportedLocales: [Locale('en', 'US'), Locale('ar', 'DZ')],
));
}
...
- 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 azbox_localization:generate -f keys -o locale_keys.g.dart
- Past import.
import 'generated/locale_keys.g.dart';
- All done!
How to use generated keys:
print(LocaleKeys.title.translate()); //String
//or
Text(LocaleKeys.title).translate(); //Widget
'en_US'.toLocale(); // Locale('en', 'US')
//with custom separator
'en|US'.toLocale(separator: '|') // Locale('en', 'US')
Locale('en', 'US').toStringWithSeparator(separator: '|') // en|US