i18n_omatic 0.2.2

i18n-o-matic makes translations easier in Flutter apps with automatic search for translatable strings in the source code.

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

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'; 

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());

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'});

Prepare configuration for translations

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>

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 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.

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'), 
    ],

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';

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.

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.