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.
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';
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());
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'});
Once the strings to translate are marked, you have to create an empty YAML file for each language you want to translate strings into and name it with the “language_country” code (e.g. fr_FR.yaml for France, es_ES.yaml for Spain, …). For Flutter applications, these files must be located in the assets/i18nomatic
directory and added in the corresponding section in the pubspec.yaml configuration file.
Example below is the pubspec.yaml section for french and spanish languages, once the files have been effectively created:
flutter:
assets:
- assets/
- assets/i18nomatic/es_ES.yaml
- assets/i18nomatic/fr_FR.yaml
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. The example below is an example for french and spanish languages:
<key>CFBundleLocalizations</key>
<array>
<string>es_ES</string>
<string>fr_FR</string>
</array>
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 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
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.
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.
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'),
],
Once this is done, every string with the .tr()
method will be translated if it is available in the target language.
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';
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
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"
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"
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.
i18n_omatic
does not support currently multiline stringsThe i18n-o-matic package is developped by Jean-Christophe Fabre.
Author: jctophefabre
Source Code: https://github.com/jctophefabre/i18n_omatic
#flutter #dart #mobile-apps