IRMA translations made easy

The IRMA app currently exists in Dutch and English. If a user’s phone is set to Dutch, the app will also be in Dutch. If their phone is set to any other language, the IRMA app will appear in English. In order to support additional languages, IRMA relies on contributions by members of the IRMA community. We have translated the IRMA app to German and documented the process to make future translations easier for the community.

If you are solely interested in the technical instructions, please have a look at the “TRANSLATIONS.md” file. This blog post explains how to contribute and translate IRMA into new languages in much more detail. It uses our translation into German (which currently is under review) as an example. It provides background information, suggests useful tools and gives advice about how to approach the translation process.

Background

Additional languages can be added to IRMA relatively easy. Currently, there is a nl.json file with the Dutch text of the app and an en.json file with the English version of the app. These .json files contain most elements of the IRMA app. Not included in the .json file are the texts that are displayed on the cards that people can load into IRMA and the information about these cards. This card-related information is stored in external scheme files (in .xml format).

The following describes how to translate both the core of the IRMA app and the card information. It assumes you are comfortable with using git and editing .json, .xml files. If you want to contribute but have no technical background, please contact the IRMA team.

Before you start

First, it makes sense to get a general understanding of the work the Privacy by Design Foundation does and the service the IRMA app provides. If you do not yet have any experiences with the application, we recommend downloading the IRMA app to your phone and trying out some demos. Additionally, we recommend reading the IRMA website and the IRMA in detail page.

In the following, we assume you know the IRMA app, so you understand how and where texts are used in the app. We assume no programming background. If you have questions, please feel free to reach out via the IRMA slack. This slack has a channel called i18n, which is dedicated to translations and other issues around internationalisation and localisation.

Tools

For our translation to German, we used several tools. Other tools might exist that suit your process better. We generally had a good experience with the following tools.

Visual Studio Code: Any text editor can be used to translate IRMA. We used Visual Studio Code (VSC) to edit the .json and .xml files. It is freeware and comes with a few features that can improve the workflow. We used the option to use search and replace across all files in a folder at once, the possibility to use regular expressions, and the ability to see two texts split-screen to compare the original and the new translation. Also, the Spell Right extension helped us with finding typos. It can use several languages simultaneously, which is useful for the .xml files that contain all languages at once.
Git: You need git to fork or clone the IRMA repositories and create a pull request when you are done with the translations.
GitHub: We used GitHub to store our files and used [GitHub’s options for comparing commits] (https://docs.github.com/en/github/committing-changes-to-your-project/viewing-and-comparing-commits) to view the differences between subsequent versions of our translations. This was especially nice because several people edited, reviewed and revised the texts. By highlighting the differences from one iteration to the next, the changes could quickly be reviewed.
Linguee: We used this translation website to find out how some phrases or words (e.g., “privacy-friendly”) in the IRMA app were translated in other texts. The website always shows a bit of context around the translated word. Seeing how a word has been translated in different contexts helped us decide when we were unsure how to best translate a particular word.
DeepL: This AI-based translation tool was used for suggestions when struggling with translating a sentence or phrase. We used it to generate alternatives when we were not happy with our own sentences. A nice option is that one can click on certain words in the translation to browse alternative translations and replace the word with another choice. When one replaces a part, the rest of the sentence automatically is updated accordingly. This allows one to play with the wording until it feels right.
LanguageTool.org: This language tool was used to find grammar and spelling mistakes in our German translation. A LanguageTool extension for VSC exists. It probably will require some fiddling with the settings before it works (e.g., the default settings assume you are running your own LanguageTool server on your machine).
i18n Manager: This tool has been designed to help manage app translations. It allowed us to view all languages at once. This was especially useful because some of us speak English, Dutch and German. Seeing all three versions of the same text next to each other gave us a good overview. It allowed us to spot when the text in one language deviated from the other two. We used this tool at the very end for the final review.

Preparations

Clone or fork the irmamobile repository
Clone or fork the pbdf-schememanager repository

Process

To translate the IRMA app, you need to create and/or edit several files in these folders.

Glossary

When editing the official files used by the IRMA app, we recommend keeping a glossary (consistency list) for yourself. The glossary should contain words and phrases that are translated more often and specify how you translate those. The list is used to ensure that those words are consistently translated in the same fashion throughout the entire app.

We recommend the following terms as a starting point for your glossary/consistency list:

cards
confirmation link
disclose
ICT
initials
IRMA app
login
make yourself known
mobile
MyIRMA
MyIRMA page
Nijmegen
online-banking
online formum
open source
phone number
pin code
privacy and security
privacy-friendly
registration
secure
user

Adding and translating the JSON file

In the IRMA app, every language has its own .json file. You find these in the irmamobile/assets/locales folder.

Create a file for your language by copying one of the files (e.g., en.json). Rename it, so it is named according to the language that you want to add. E.g., to add a German translation based on the existing English version, we copied en.json and renamed our copy to de.json.

This .json file is the main file that needs to be translated. In this file, you need to keep all keys in place but translate all the values.

We edited the files with VSC. In the end, we reviewed the result with the i18n Manager application. This tool has the advantage that one can few all existing translations simultaneously (see screenshot).

Elephant at sunset — *Screenshots:* The **i18n Manager application** was used to view all translations simultaneously.

Extending the app.dart file

A few lines of code in the app.dart file tell the IRMA app what languages exist. This file is part of the IRMA app’s code and needs to be extended with one simple line so the app knows about the new language that has been added. You can find it here: irmamobile/lib/app.dart. You do not need to know dart/flutter.

In the app.dart file, you will find a section like this:

static List<Locale> defaultSupportedLocales() {
    return const [
      Locale('en', 'US'),
      Locale('nl', 'NL'),
    ];
  }

Add your language below the existing ones. E.g., to add German, we append the following file:

static List<Locale> defaultSupportedLocales() {
    return const [
      Locale('en', 'US'),
      Locale('nl', 'NL'),
      Locale('de', 'DE'),
    ];
  }

Adding translations to the scheme files

The IRMA app also uses some external files. These files describe the cards that can be loaded into IRMA. They define the text displayed on IRMA cards and the information provided about the cards in the in-app card overview. We call these files the “scheme files”. (This separation between the card information and the IRMA app is very useful. For instance, when issuers start issuing new cards, the IRMA app neither needs to be changed by developers nor updated by end-users.)

You find the scheme files in the pbdf-schememanager folder. The files that describe the IRMA cards are placed in different folders, depending on who issues the card. They are all called description.xml. These files contain all translations in corresponding tags. E.g., Dutch texts are included in tags, and English texts are included in tags.

Add tags for the new language to all description.xml files and add your translation between these tags.

To translate the app to German, we automatically added a German tag-pair after all Dutch tag-pairs for all files in pbdf-schememanager. (In the pbdf-schememanager folder, we used regular expressions to replace ^(.*)(<nl>.*?</nl> *\n) with $1$2$1<de></de>\n). We then added the translations to those German tag-pairs.

Here you can see a snippet of /pbdf-schememanager/gemeente/Issues/address/description.xml before the addition:

		<en>Home address</en>
		<nl>Woonadres</nl>

The same snippet after the addition:

		<en>Home address</en>
		<nl>Woonadres</nl>
		<de>Heimatadresse</de>

You can also replace lines that are used more often throughout all files. In VSC you can use the shortcut Ctrl+Shift+H to search and replace through several files and then, e.g., search for

		<nl>Persoonlijk</nl>
		<de></de>

and replace it with the same, including the new translation:

        <nl>Persoonlijk</nl>
        <de>Persönlich</de>

This can be done for every instance of name, short name and category. This way, you can reduce the manual work for the translation.

The remaining parts are easily translated by hand. Most of the description.xml files are very short and simple. A few files contain larger junks of text. These files all feature a <IsInCredentialStore>true</IsInCredentialStore> tag. They concern cards that are prominently featured in IRMA. Users can learn more about these cards right from within the app. The additional information that is presented includes, e.g., what users can do with the card and how they can obtain it. This information is part of the scheme files and needs to be translated just like the rest of the scheme. For these explanatory texts, it is also useful to make a consistency list (see above). Several phrases occur repeatedly but cannot easily be translated automatically, e.g., You will add the following data:.

Create pull requests

Once you have completed the translations, create pull requests for the changes in the irmamobile repository and for the changes in the pbdf-schememanager repository.

Conclusion

Translating IRMA entails a few technical steps and comes with some language challenges. For those comfortable with git and editing .json and .xml files, the technical process is straightforward, and no programming background is necessary. However, it cannot be assumed that everyone who wants to contribute has the required technical skills already. To overcome this, translators and developers can collaborate - so that the translators can solely focus on the language aspect. Yet, it would be desirable to streamline the process in the long term and use a web-based tool for translators to reduce the effort and lower the barrier for those willing to contribute.

With respect to the language challenges, the IRMA app requires quite some proficiency with terms evolving around privacy and identity management. When translating the app to German, we noticed quite a few terms with no perfect German equivalent. Because of this, it is imperative to understand the IRMA app and underlying philosophy before translating IRMA. The IRMA community has this understanding, so we hope that more languages will be added by the community in the future.

Translating IRMA to a new language always will come with some challenges. However, we hope the experiences we shared about translating IRMA to German will make it easier for others to add new languages.