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 photools.community if you have questions.
How It Works
- When an app starts, it first looks for the default resource file
resource-en.json. This file must always exist. - The app then gets the user interface language for the current user from IMatch and looks for a resource file for that language.
- If a resource file for the user language is found, it is loaded and replaces the default (English language) 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.
[font_text icon=”info-circle” color=”dark” size=”medium”] 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.[/font_text]
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):
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:
C:\ProgramData\photools.com\IMatch6\webroot\imatch\apps\app-translator\res
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:
- To start a new translation, make a copy of the default resource file
resource-en.jsonand rename it to match the target language.
For example,resource-de.jsonfor German (language code de). - Open the resource file in a text editor and translate each value into the target language.
- 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:
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.
The Scan for Changes button is used together with Diff files (see below). It allows you to quickly scan for new and updates resources after a new release of IMatch came out. Or after you have received a resource update from photools.com
To make this easier, we’ve added a command to the App Manager that allows you to open the App Translator for any app:
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.
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.
[font_text icon=”hand-o-up” color=”dark” size=”medium”] Tip: Click on the Hotkey button at the top to display all keyboard shortcuts.[/font_text]
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.
[font_text icon=”floppy-o” color=”dark” size=”medium”] The App Translator automatically saves your changes in the background while you work with it.[/font_text]
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:
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.
[font_text icon=”hand-o-up” color=”dark” size=”medium”] 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.[/font_text]
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 with the name resource-en.json.diff. 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.
Scanning for Changes
This command scans all apps for new or modified resources. It produces a list of changed apps. You can start updating outdated translations directly from this list. Use this command after you have installed an IMatch update or after you have received new resource files from photools.com.
This command relies on diff files which must be present in all folders. photools.com provides diff file sets for all versions after IMatch 2017.14.2.
Installing the Diff File Set
photools.com provides diff file sets as ZIP files. The ZIP files have the same structure as the C:\ProgramData\photools.com\IMatch6\webroot\imatch\apps folder hierarchy on your hard disk. You extract the contents of the ZIP file into this folder, which puts the diff files into the correct locations.
Verify: After extracting the file, each \res folder in the app folders must have a resources-en.json and resources-en.json.diff file.
You can download the diff files at the end of this page.
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:
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 photools.com customer portal when you download IMatch or IMatch Anywhere updates.
[font_text icon=”info-circle” color=”dark” size=”medium”] This is currently a limited premium feature.
Your user account must be explicitly enabled before you can use it. Please contact photools.com support if you want to use machine translation in the App Translator. [/font_text]
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 photools.com 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 photools.com 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:
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.
Summary
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.
Diff File Sets for IMatch
These ZIP files have the same folder structure as C:\ProgramData\photools.com\IMatch6\webroot\imatch.
Download the ZIP, for example on your Desktop. Then Double-click on the ZIP in Windows Explorer to open it. Click on the folder on the top-level (with the version name). Below that you’ll find a folder named imatch:
Copy this folder into the clipboard and then open the folder C:\ProgramData\photools.com\IMatch6\webroot\ (this folder already contains a folder named imatch, this tells you you are in the right place). Paste the imatch folder from the clipboard into this folder. This will place the diff files into the correct folders.
Which Set to Use?
You install the resource file from the previous version. For example if you run IMatch 2018.8.2 you download and install the 2018.7.8.zip, because this allows you to see all changes done between the 7.8 and 8.2 releases.
Note: If you have skipped one or more translations, start with the Diff File Set of the version for which you have last supplied a translation. For example if you run 8.2 but you did not do translations for 7.6 and 7.4, you start with the 7.4 file set. After checking what has changed in App Translator and adding the missing translations, you download the 7.6 file set and repeat.
To download a diff file, use an URL formed by https://www.photools.com/bin/res-diff/<YYYY.M.R>.zip.
For example, for the diff file for IMatch version 2020.4.2, use https://www.photools.com/bin/res-diff/2020.3.6.zip.
If there is no diff file for a release, the browser returns “Not found”.