i18n_omatic

Description:

i18n omatic

i18n-o-matic #


i18n-o-matic is a dart package to make translations easier in Flutter apps.
It provides the ability to automatically search for translatable strings in the source code and builds translations tables for each language.
This approach is inspired by the one used in the Qt framework.

🏖 Painless translation workflow
🔎 Automatic discovery of translatable strings
👩‍💻 Human readable YAML format for translations files
#️⃣ Formatable strings for variable substitutions

Contributions to this package are welcome 🎉👍, see the CONTRIBUTING Guidelines for more information.
How it works #
i18n-o-matic uses original strings marked as translatable in the source code and use them as as translation keys.
The I18nOMatic class replaces each translatable string by the corresponding string of the current language.
It is advisable to use English as the reference language of the strings to be translated in the application.
First of all, each source file with translatable strings must import the i18n_omatic package:
import 'package:i18n_omatic/i18n_omatic.dart';
copied to clipboard
Mark strings as translatable #
To mark a string as translatable, it must be applied the tr() method provided by i18n_omatic:
String firstString = 'My first string'.tr();
// ...
Text('Share on network'.tr());
copied to clipboard
When parts of the translatable string are based on external values (aka string interpolation), placeholders in the string can be used with a provided key-value table. These placeholders begins with a % character and must be named with the corresponding key in the table:
String birthdayMsg = 'Happy birthday %name, you are %age years old'.tr({name: 'Peter', age: '21'});
copied to clipboard
Prepare configuration for translations #
Once the strings to translate are marked, you have to edit the pubspec.yaml configuration file of your Flutter application and add an asset file for each translation language.
These files are located in the assets/i18nomatic directory
and named with the "language_country" code (e.g. fr_FR.yaml for France, es_ES.yaml for Spain, ...).
They will be created and updated using the update tool (see below)
Example of the pubspec.yaml section for french and spanish languages:
flutter:
assets:
- assets/
- assets/i18nomatic/es_ES.yaml
- assets/i18nomatic/fr_FR.yaml
copied to clipboard
For iOS, the file ios/Runner/info.plist must be updated to register the supported locales.
The CFBundleLocalizations must be added or updated with an array of the supported languages. Example for french and spanish languages:
<key>CFBundleLocalizations</key>
<array>
<string>es_ES</string>
<string>fr_FR</string>
</array>
copied to clipboard
Automatically build translation tables #
The i18n_omatic package provides a command line tool that will scan the source code of the application and search for the translatable strings. Then, it will create or update the translation files with the found strings.
The following command line has to be run in the root directory of the project:
dart pub run i18n_omatic:update
copied to clipboard
By default, this command line tool wil scan the lib directory recursively, looking for .dart files, and will update the translations files located in the assets/i18nomatic directory. If a translation file declared in the pubspec.yaml file does not exist yet, it is automatically created.
You can run this tool whenever needed to update the translation tables
with the newly translatable strings introduced in your source code. The previously translated string will remain in the translation files.
Enable translations in application #
You have to enable the i18n_omatic localization delegate and add the supported locales in your application definition class.
Do not forget to add the locale of the translatable strings in your source code, as it can be considered as the default application language (usually en/US).
MaterialApp(
// ...
localizationsDelegates: [
I18nOMatic.delegate,
GlobalMaterialLocalizations.delegate,
GlobalCupertinoLocalizations.delegate,
GlobalWidgetsLocalizations.delegate,
],
supportedLocales: [
const Locale('en', 'US'),
const Locale('fr', 'FR'),
const Locale('es', 'ES'),
],
copied to clipboard
Once this is done, every string with the .tr() method will be translated if it is available in the target language.
Edit translation files #
Given the following part of ource code:
String firstString = 'My first string'.tr();
// ...
Text('Share on network'.tr());
// ...
String birthdayMsg = 'Happy birthday %name, you are %age years old'.tr({name: 'Peter', age: '21'});
// ...
String ingnoredString = 'ignored string';
copied to clipboard
At the first run of the i18n_omatic:update command line tool,
the following file will be generated for the french language (assets/i18nomatic/fr_FR.yaml):
format_version: 1

strings:
"My first string" : null
"Share on network" : null
"Happy birthday %name, you are %age years old" : null
copied to clipboard
The 3 collected strings are now available for translation but are null by default. You have to edit the file and provide correct translations as follow (example for french):
format_version: 1

strings:
"My first string" : "Ma première chaîne de caractères"
"Share on network" : "Partager sur le réseau"
"Happy birthday %name, you are %age years old" : "Bon anniversaire %name, tu as %age ans"
copied to clipboard
If you remove one or more translatable string (e.g. firstString in the example above) in a further development
and run again the i18n_omatic:update command line tool,
these translated strings will not be lost and will be placed in a unused_strings category:
format_version: 1

strings:
"Share on network" : "Partager sur le réseau"
"Happy birthday %name, you are %age years old" : "Bon anniversaire %name, tu as %age ans"

unused_strings:
"My first string" : "Ma première chaîne de caractères"
copied to clipboard
Once you are sure you will not use these strings anaymore, you can remove them from the yaml files.
You are encouraged to clean up these files before releasing a new version of your application.
How to test a Widget which uses i18n_omatic #
You can use the Mockito package to mock the translation of the tr() function :
import 'package:i18n_omatic/i18n_omatic.dart';
import 'package:mockito/mockito.dart';

class MockI18nOMatic extends Mock implements I18nOMatic {}

class MockSetUp {
static void mockI18nOMatic() {
I18nOMatic.instance = MockI18nOMatic();
when(I18nOMatic.instance.tr(any, any)).thenAnswer((realInvocation) {
var strTranslated = realInvocation.positionalArguments[0].toString();
if (realInvocation.positionalArguments[1] != null) {
realInvocation.positionalArguments[1].forEach((String key, String value) {
value ??= '';
strTranslated = strTranslated.replaceAll('%$key', value.toString());
});
}
return strTranslated;
});
}
}
copied to clipboard
and call MockSetUp.mockI18nOMatic() at the beginning of the Flutter widget test :
void main() {
setUp(() {
MockSetUp.mockI18nOMatic();
});
[...]
copied to clipboard
Known limitations #
Currently, i18n_omatic does not support

multiline strings
left-to-right languages such as Arabic or Hebrew
automatic management of plural forms

Author #
The i18n-o-matic package is developped by Jean-Christophe Fabre.
Contributors:

Aurélien Joubert 💻 📖