App Translator Icon

The Basics

IMatch Apps are shipped in English language (the default language) and usually with a German language translation (because Mario is from Germany).
Translations for other languages can be added by creating language resource files. The App Translator App included in IMatch makes it easy to create, display and edit these resource files.

How You Can Help

Translating an app into another language takes between 5 minutes and maybe one or two hours for complex apps like the Map Panel. If you want to see more IMatch apps in your language, please help by creating a translation. This short guide shows you how. Contact us via the if you have questions.

How It Works

  1. When an app starts, it first looks for the default resource file resource-en.json. This file must always exist.
  2. The app then gets the user interface language for the current user from IMatch and looks for a resource file for that language.
  3. If a resource file for the user language is found, it is loaded and replaces the default (English language) resources.


IMatch App Resources

This graphic shows an app with the default resource file and two additional resource files: resource-de.json (German) and resource-nl.json (Dutch).

If the user has configured IMatch to use the German (de) user interface language, the app will find and use the resource-de.json file. For user interface languages other than German or Dutch (nl), the app uses the default English resource file.

And this is where you come in: by creating a resource file for your language, you can teach an app to speak your tongue.

The following section explains some of the technical background of how apps use resources.
If you are not interested at this time, skip to the The App Translator section below.

Structure of Resource Files

IMatch Apps use UTF-8 encoded JSON text files for storing resources. JSON files can be edited with every text editor which supports UTF-8 encoding (Notepad++, Visual Studio Code, etc.).

Here are two segments of such a JSON resource file: At the top is the default resource (English language) and below that the corresponding section of the resource-de.json (German language):

JSON Resource Format

As you can see, it’s a simple key : value structure. Each resource has a unique key (name) and a value. The image shows the keys in blue color and the values in brown color.

IMatch Apps access resources via their key and then uses the value for whatever purpose. The key is the same in all resource files and the value differs between English, German and other translations.

Partial Translations

If a resource file has no value for a given key, the app automatically uses the value from the default resource file. This allows for partial translations, e.g. while a translator is still working on a translation or when a new version of the app is released and not all translations are updated at the same time.

The ‘res’ Folder

Most apps store their resources in a folder called res inside the app folder. For example:


contains the resource files for the App Translator app.

Manually Editing Resources

If no other tools are available (there are, see below), a translation can be created in any standard text editor that supports UTF-8 encoding. The process is easy:

  1. To start a new translation, make a copy of the default resource file resource-en.json and rename it to match the target language.
    For example, resource-de.json for German (language code de).
  2. Open the resource file in a text editor and translate each value into the target language.
  3. Save your resource file.

Important Tips

  • Make sure you don’t accidentally remove the ” and ” surrounding the key and value. These are required by JSON.
  • Each line ends with a comma.
  • No line-feeds are supported inside ” and “.
  • All text goes between ” and “.
  • If you have to include the ” character inside one of the values, you have to escape with \, it like so: "This is \"text\" inside a JSON string".
  • If a resource contains HTML tags enclosed in <> (e.g.,  <strong> ,<span> or similar) put the same tags in the appropriate place in your translations. These tags control formatting or other important aspects of the app.
  • If a resource contains placeholder tokens like {0} or {source}, include the same token in your translation in the appropriate location. These tokens are replaced by numbers of texts by the app at runtime.
  • HTML tags use the <tag></tag> syntax (tag, end tag). There is no space between < and / in end tags: </tag> is correct, < /tag> or </ tag> are wrong.
  • Use a capable text editor like Visual Studio Code, Atom, or Sublime. These understand JSON and will tell you if your file has syntax errors. IMatch apps cannot load invalid JSON files.

See Your Changes

If you save a resource file, IMatch reloads the app automatically, showing you the current state of your translation.

If you run the app in a web browser, press F5 to reload the page. Sometimes you may need to force a cache refresh (Shift+Del) or disable the cache in the browser’s developer tools to force a reload of the modified resource.

The App Translator App

This app makes it easy to create new translations and to edit and update existing translations. To start the app, click on the app icon in the App Manager.

If you have not used the App Translator before, it starts up like this:

This is how the App Translator app looks initially.

The first thing is to switch to the language you want to create translations for. For this, left-click or tap on language selector field. In the screen shot, we’ve switched the language to de (German). The app remembers your settings for the next time you run it.

Now click on Open Translation. This opens a folder browser dialog box where you can select the folder containing the resources for the app to translate. As explained above, apps usually store their resources in a folder called res inside the folder containing the app. You are looking for the folder that contains the resource-en.json file for the app.

To make this easier, we’ve added a command to the App Manager that allows you to open the App Translator for any app:

Launching the App Translator from the App Manager


This launches the App Translator and automatically loads the resources for the app. For the following examples we used the CSV Import App.

Using the App Translator

This is how the App Translator looks after loading a resource file. The resource file in this example is already partially translated into the German (de) language.

The App Translator with a resource file.

At the top you see a table with all key/value pairs in the resource file. In the Default column you see the default value (English) and in the Translated column you see the value in the translation language.

To translate a value click on it in the table, or use the navigation buttons at the bottom of the app to move between values.

Tip: Click on the Hotkey button at the top to display all keyboard shortcuts.

The key currently selected value is displayed in the white box. Below the value for the key is shown, followed by the input field where you enter your translation.

The App Translator automatically saves your changes in the background while you work with it.

Lets do some translation work. We translate the English text “Record Delimiter:” into the German text “Datensatztrennzeichen:”. To do this, we write the German translation into the Your Translation input field:

Some resources translated

The App Manager adds the translation to the resource file and updates the table. The resource file is automatically saved. The translation counter at the bottom is updated to show us how many translations there are to do (1).

That’s basically all you have to do. You go from key to key and translate each value into your language. To see your changes, keep the app running in IMatch or press F5<&/kbd> in your web browser to reload the app.

The Auto Backup

When you open a translation, the App Translator saves the current version of the translation in a file with the extension .bak, For example, if you work on the German translation, the backup file is named resources-de.json.bak. You may want to copy this file to a safe location in case you need to undo some of your changes.

As always  with important data, you should do backups of translated resources often. Especially while you work on your translation. Just copy the resource files into another folder under a unique name. This way you can always revert back to an earlier version of your translation or recover from a problem.

Updating Translations

When a new IMatch version is released, it may ship with an updated version of an app you have translated. To update your translation you just open the res folder in the App Translator again. Find values which need translating and translate them. Usually there are some new values and maybe some of the previously existing values have been  modified.

Finding Modified Values

It may happen that a newer version of the app ships with modified default resources. This means that your translation is probably not longer correct and requires updating.

But how to detect modified values quickly? Is there a way to see the differences between versions of a resource file? Yes, there is.

The Diff File

The App Translator has a feature called a diff file. This works as follows:

When you open a translation, the App Translator checks if there is a Diff file for the resource-en.json. If this file exists, it is loaded and its contents are compared with the contents of the resource-en.json file. If the resource-en.json has been modified, the App Translator will see the differences between it and the Diff file and use that to show you added and modified resources.

If a new version of an app is installed, all you need to do is to open the App Translator and you will immediately know if there are new resources to translate or existing resources to update.

Values no longer in the default resource file are automatically removed from your translation when it is saved. New and modified values are indicated in the key/value table like this:

In the example above, the value for key T_HELP_TITLE was modified since you created the diff file. And the T_PROMPT value was added since then. This feature makes checking a resource file for changes very easy.

If no Diff file exists, the App Translator will ask if you want to create one when you open the resource. You can also create Diff files at any time via the toolbar button.

Special Characters and Tokens

If a resource contains HTML tags enclosed in <> (e.g.,  <strong> ,<span> or similar) put the same tags in the appropriate place in your translations. These tags control formatting or other important aspects of the app.

HTML tags use the <tag></tag> syntax (tag, end tag). There is no space between < and / in end tags: </tag> is correct, < /tag> or </ tag> are wrong.

If a resource contains placeholder tokens like {0} or {source}, include the same token in your translation in the appropriate location. These tokens are replaced by numbers of texts by the app at runtime.

HTML Preview

If a translated resource contains HTML tags, the App Translator displays a HTML preview at the bottom. This allows you to tell if your translation works and if all HTML tags are properly formatted:

HTML Preview in the App Translator


A.I. Machine Translation

The App Translator supports machine translations. While not being perfect, this feature can do the grunt work for you. It translates a resource file with 50 keys and several Kilobytes of text in a few seconds. It’s very good at translation things like button captions, control texts and similar. It may come up with funny or plain wrong translations for longer, more complex texts. Which is to be expected, given that it has no context knowledge and does not know that it translates an IMatch app.

The general idea is to let the machine do the initial rough translation. Then you go over the results, doing some corrections where needed. Initial tests show that this reduces the time required to translate an app by at least 50%!

Using Machine Translation

To translate all or not yet translated resources in the currently loaded resource file, click on the Auto Translate button at the top.

If you have not used that feature before, it will ask you for your email and license key. Enter the same email and license key you use to log into the customer portal when you download IMatch or IMatch Anywhere updates.

This is currently a limited premium feature.
Your user account must be explicitly enabled before you can use it. Please contact support if you want to use machine translation in the App Translator.

Providing your credentials for machine translation.

Enable the Save my access token for later sessions  if you don’t want to provide your credentials every time you run the App Translator. The app then stores the access token for this specific service in encrypted form in the app storage facility. This token does not contain any personal data and cannot be used to download software from or anything. It’s just used for this app and this service.

After you have successfully logged in, the App Translators asks whether you want to translate everything or just the values without a translation (preferred). After the translation has been completed, machine-translated values are indicated with a special color in the table:

Machine-translated values.

You can now review these values and modify them as needed. Especially for the initial translation of a new app this saves a lot of time.

Sharing Translations

Naturally, you don’t create a translation just for yourself. It’s way more fun if you share your translation with all other IMatch users who speak your language.

Send the resource file with your translation to us, and we’ll include it the next IMatch release. Please include the name of the app in your email so we know to which app the resource belongs.


Translating IMatch apps is done by volunteers – like You!

With the integrated App Translator you have a free and powerful tool to quickly create and update translations for IMatch apps. The A.I. machine translation supports you by doing the grunt work of doing the initial translation of the resource file.