This page explains how to translate IMatch into other languages.

The IMatch XML Resource File

IMatch has been designed from ground up to manage all resources in XML files. Every menu command, text, bitmap, message, dialog box etc. you see in the IMatch user interface is controlled by one single resource file in XML format. The proprietary photools.com resource manager technology uses this XML file to dynamically create the IMatch user interface at runtime.

To translate IMatch into another language only these XML files needs to be modified. Since the file is a plain text file following the XML syntax you can use any text editor or XML editor to modify it.

If you don’t have a text editor yet, try the free Visual Studio Code

IMPORTANT: Please always use a tab size (tabulator size) of 4 and don’t let your editor replace tabs with spaces. This way the document will look identical for all translators.

The IMatch resource file is named imatchres.xml and can be found in the following folder:

%PROGRAMDATA%\photools.com\IMatchN\resources

The N stands for the IMatch version, e.g. “6” for IMatch 2017: %PROGRAMDATA%\photools.com\IMatch6\resources.

GITHub

IMatch resources are managed as a project at GitHub:

https://github.com/photools/imatch-resources

The branch next_release is the branch we manage for the next IMatch release. If you want to make changes, CREATE A BRANCH from that branch, make your changes, COMMIT them with a proper comment and then create a PULL request.

Resource Files

IMatch uses several resource files (all in the folder specified above):

  • imatchres.xml (commands, menus and global resources)
  • imatchres_str.xml (string resources)
  • imatchres_dlg.xml (dialog resources)
  • imatchres_msg.xml (message resources)
  • impagres.xml (Pack & Go Resources, all in one file)

If you start with translating, start with Pack & Go. There is only one resource file and you can quickly close and re-open Pack & Go to see your translation updates.

Example: A Command Resource

The following XML statement describes an IMatch command. A command is used in a menu or a toolbar. The resid is the unique id of the command, ID_APP_EXIT in this case. This command is used to exit IMatch:

<cmd resid="ID_APP_EXIT" helpid="">
    <c xml:lang="en" helptext="Closes this application">E&amp;xit</c>
    <c xml:lang="de" helptext="Beendet die Anwendung">B&amp;eenden</c>
</cmd>

The highlighted parts are the parts which need to be translated. As you can see, the command has two language-specific <c>-nodes. A <c> node has a xml:lang attribute which specifies the language, a helptext attribute and finally the actual content, between > and </c>.

The first <c> node specifies the help text and command name to use for the English language (“en”). The second node specifies the help text and command name for the German language (“de”).

If you want to add a translation for the French language, just add a third <c> node with the French help text and command name:

<cmd resid="ID_APP_EXIT" helpid="">
    <c xml:lang="en" helptext="Closes this application">E&amp;xit</c>
    <c xml:lang="de" helptext="Beendet die Anwendung">B&amp;eenden</c>
    <c xml:lang="fr" helptext="Quitte l'application">&amp;Fin</c>
</cmd>

When you add resources for a new language, please always append to the existing resources (in the above case, your <c> node would be added below the node for the “fr” language node.

&amp;

The &amp; escape token is used to insert an & character into the text. Because & has a special meaning in XML, it cannot be used directly. The character following the &amp; will be used as the hotkey in menus. So, E&amp;xit will show as Exit in menus and the x will be the underlined hotkey.

Hotkeys defined with &amp; are always local to the menu or dialog box which contains the command or control. Just make sure that commands used in the same menu or dialog box don’t use the same &amp; hotkeys. Otherwise the user will not be able to access the menu entries via the hotkey.

IMatch checks for menu items with duplicate hotkeys at program start and reports them to the application log file. Search for the text “Duplicate hotkey” to find these commands.

Editing the XML Resource File

After getting the latest version from the GITHub, open the imatchres.xml file in your text editor. Make sure you use a text editor with syntax highlighting and UTF-8 support, like Visual Studio Code.

IMatch assumes that the resource file is syntactically correct. There is limited error checking and IMatch cannot start if the resource file cannot be loaded. But if you only change the parts designed for translation there is only a minimal risk of corrupting the file structure.

In case errors are detected while loading the resource file IMatch writes messages into the standard log file IMATCHX_LOG.TXT. This file is stored in the temporary folder on your computer. To open this folder in Windows Explorer, type this into the Windows Explorer address bar:

%TEMP%

It is a good idea to always keep previous versions of the XML file on your disk so you can revert back when something goes wrong. Usually you will never run into trouble as long as you only translate but not change the resources.

Rules & Tips

Here are a few simple rules which will help to prevent problems:

  • Never change a resid=attribute or touch any other part of the XML not required for translating
  • Never change the order of elements or XML nodes
  • Attributes are always enclosed in “, like: helptext=”abcd”
  • The content of a node is always between the > and the < of the node
    e.g. …>Bla</c> for a command node
  • Certain characters are reserved in XML files and cannot be used. Instead you have to use escape tokens:
    < must be written as &lt;
    > must be written as &gt;
    & must be written as &amp;
  • IMatch sometimes uses <![CDATA[ … ]]> constructs to include XML or HTML data in the resource file. When you edit these sections, make sure that the opening <![CDATA[ and the closing ]]> remain untouched.
  • You can load the XML file into your web browser for testing purposes.
    If there is a syntactical error, e.g. a > or & added in the wrong spot without proper escaping, the browser will refuse to load the file and display an error message.
    If the browser likes the XML, IMatch will also like it.
  • The XML file uses comments in <!– and –> to explain things or give additional information about the usage of a specific resource. This is information four you to help during translation.
  • Sections which need special care have been marked with an @Translators comment.

Special Features for Translators

The Resource Manager Menu

IMatch includes a number of features designed to support translation. You can access these functions via the the Resource Manager menu. This menu is by default not visible. To enable it you need to add an entry into the Windows Registry on your computer.

Download this ZIP file and unpack it on your computer.

IMatch Registry Files

Then double-click on the file imatch5_translator.reg to add the special key to the IMatch registry settings. After restarting IMatch you will have access to the Resource Manager menu.

Resource Manager Menu

This menu gives you access to a number of special commands. The Toggle Translator Mode command, if enabled, tells IMatch to log resource access internally and to add some extra functionality to dialog boxes which help during the translation process. You should enable this on your computer.

If Translator Mode is enabled, dialog boxes show an extra button with a T* caption in the lower left corner:

T* button in dialog boxes

When you click this button, the dialog displays overlays to show the outline of each control and the corresponding resid from the XML resource file.

Dialog Box in Translator Mode

This enables you to tell which control in the dialog is filled from which entry in the dialog resource. You can also see how much screen space is available for translated text. This is of special importance for languages which require more text than English, e.g. German or French.

The List resources without translation command is a big help when new IMatch versions are released. This command produces a log file of all resources with missing translations for the current language. Each new IMatch release may bring a few new commands, dialog boxes, strings etc. which require translation. Use this command to find these resources quickly.

The History… command allows you to see which resources have been used recently.

History dialog box

This makes it easy to figure out which resource in the XML was used for a menu, string, dialog box, message or other UI element.

The Reload Resource File… command allows you to reload the XML resource file without restarting IMatch. Changes made to string, dialog, message etc. resources can immediately be controlled in the IMatch user interface.

Changes made to some resources, like the commands used to built toolbars etc. require a reload of the database or even an application restart to become visible. You can do both from the Resource Manager menu.

You can also switch the language in this menu. You need to restart IMatch after changing the language in this menu.

See the Developer Resources menu on the right for detailed information about translating the different resource types used by IMatch.

Changes of Existing Resources – Diff

Sometimes we need to change existing resources, which probably also requires updates to existing translations.
To see all changes done on the resource files between versions use the DIFF command available in the GitHub desktop application or whatever Gut Client you use. There are also free file like WinMerge which allow you to compare files and see changes.

Standard Terminologies and Translations

An important resource for translators is the Microsoft Language Portal. Here you can search for “standardized” translations of many of the commands used by IMatch. If you want to know how Microsoft would translate commands like “Open”, “Delete” or “Paste” into other languages, check out this web site. This makes it easier for users who also use Microsoft products, if the same command is named identically in IMatch and Windows / MS products.

Resource Type: String

Strings are used throughout the application for a wide range of purposes, ranging from status bar messages to predefined category names like “@All” or “@Keywords”.

The <string_table> node contains any number of <string_group> nodes. String groups are ignored by IMatch, they are only used to add another level of organization for programmers and translators. Each <string_group> contains one or more <str> nodes.

Syntax

<str resid="RESID" desc="Optional description">
  <s xml:lang="lang">Value</s>
</str>
RESID The unique resource identifier for this string.
desc An optional description. No translation is required for this.
lang The lang identifier for this <s> node. A <str> node contains one <s> node for each language.
Value The value is the part that needs translating.

Example

<str resid="PTR_DAY_1" desc="Day Name for Monday">
  <s xml:lang="en">Monday</s>
  <s xml:lang="de">Montag</s>
</str>

When you add <s entries for new languages, always append to the list of existing <s> nodes. In the above case, add your string under the “de” string. This makes it easier for the version control system to merge changes later.

Resource Type: Dialog

Dialog boxes and property pages are used to both display and gather information from the user. Dialog boxes can be simple or complicated, which also reflects in the associated resources in the XML resource file.

The <dialog_table> table node contains any number of <dialog> nodes. A <dialog> node contains a <caption> node, one or more <ctrl> nodes and zero or more <textdata> and <listdata> nodes.

The <ctrl> node represents a control in the dialog, like a button, static text etc. <listdata> is used to fill list boxes and combo boxes in the dialog. <textdata> nodes are used to include arbitrary text in the dialog. <textdata> is used for a wide range of purposes.

Syntax

<dialog resid="RESID" desc="desc">
    <caption xml:lang="lang">Caption</caption>
    <ctrl text="ctrlid">
        <c xml:lang="lang" helptext="Help">Control Text</c>
    </ctrl>
    <textdata>
        <td tid="tdid">
            <t xml:lang="lang">Text data</t>
        </td>
    </textdata>
    <listdata text="RESID">
        <ld listid="ldid">
            <l xml:lang="lang">List Text</l>
        </ld>
    </listdata>
</dialog>
RESID The unique resource identifier.
desc An optional description. This is not translated.
ctrlid The id of the <ctrl> node as used in the dialog box.
lang The ISO lang identifier
Caption The caption of the dialog box
Help The help text is displayed in tooltips and sometimes also in the dialog itself.
This attribute is optional.
Control Text This is the text that is displayed in menus. IMatch automatically appends the Hot-Key to this text if a Hot-key is defined for the command.

Although dialog boxes are internally often very complicated and carry a great deal of logic, translating dialog boxes is pretty straightforward.

For most dialog boxes you only have to translate the <caption> and the <ctrl> nodes. <listdata> and <textdata> are only sporadically used.

Dialog Translation Helper

When the translator mode is enabled in the Resource Manager menu, dialog boxes display an additional button in the lower left corner. When you click this button, IMatch overlays each control element in the dialog (text, buttons, …) with the corresponding ctrlid of the corresponding<ctrl> node. This makes it much easier to translate the control and to make sure that the translated text fits into the available screen space.

Example

<dialog resid="PTRMDLG_SORT_NEW" >
  <caption xml:lang="en">New Profile</caption>
  <caption xml:lang="de">Neue Sortiervoreinstellung</caption>
  <ctrl text="#l_preset_name" >
     <c xml:lang="en" helptext="">Name of the new profile:</c>
     <c xml:lang="de" helptext="">Name der neuen Voreinstellung:</c>
  </ctrl>
  <ctrl text="#l_msg_duplname" >
    <c xml:lang="en" helptext="">This name is already in use. Sort P(...)</c>
    <c xml:lang="de" helptext="">Dieser Name wird bereits verw(...)</c>
  </ctrl>
</dialog>

This dialog resource is used for this dialog box:

Dialog SampleResource Type: Message

Messages are templates used by message boxes you see in IMatch. Whenever IMatch brings up a message box, “Are you sure” prompt or similar, a message resource is used.

The <message_table> node contains any number of <message_group>nodes. These groups are only used as an aid for programmers and translators, IMatch ignores them. Each <message_group> contains one or more <msg> nodes

Syntax

<msg resid="RESID" typeid="type" desc="desc">
  <m xml:lang="en">
    <cap>Caption</cap>
    <cont>Content</cont> -->
    <ftr>Footer</ftr>
    <inf>Information</inf>
    <ver>Verification</ver>
    <button btnid="BtnID">Button</button>
</m>
RESID The unique resource identifier for this command.
type The type of the message.
desc Optional description. Not translated.
lang The lang identifier for this <m> node. A <msg> node contains one <m> node for each language. See Language Attributes for more information.
Caption The caption / headline for the message box
Content The text / content displayed in the message box.
Footer This is an optional part.
Some message boxes display additional information (e.g. security tips) in the footer area.
Information This is an optional part.
Some message boxes show an “Info…” button which expands an additional area in the message box.
Verification This is an optional part.
Some message boxes show an verification check box, like “Don’t show again”.
Button If a message box uses additional buttons, they are listed here.

Example:

<msg resid="PTR_MSG_RESMGR_RELOAD" typeid="[[TD_INFORMATION_ICON]]">
    <m xml:lang="en">
        <cap>Reloading Resources</cap>
        <cont>This will reload changes made to the resource (...)</cont>
        <ftr typeid="[[TD_WARNING_ICON]]">Errors in the resource (...)</ftr>
    </m>
</msg>

This resource produces this message box:

Message Box

Resource Type: Menus

Menu resources are used or the menus in the main menu bar and also for all context and drop-down menus.

The <menu_table> node contains any number of <menu> nodes. A menu contains a <name> node and any number of <item> nodes. <item> nodes specify commands to include in the menu. The <name> node has one <n> node for each supported language.

Syntax

<menu resid="RESID">
  <name>
    <n xml:lang="lang" helptext="Help">Menu Name</n>
  </name>
  <item>Command ID</item>
</menu>
RESID The unique resource identifier for this command.
lang The lang identifier for this <n> node. A <name> node contains one <n> node for each language. See Language Attributes for more information.
Help The help text is displayed in toolbar tooltips and in the application status bar when the user moves through a menu.
This attribute is optional.
Menu Name This is the text that is displayed in menus. Use an ampersand & (encoded as &amp;) to indicate the menu access key. This letter will be displayed with an underscore in the menu.

Example

<menu resid="IDM_DATABASE_MENU">
  <name>
    <n xml:lang="en" helptext="Database Commands">&amp;Database</n>
    <n xml:lang="de" helptext="Datenbank-Operationen">&amp;Datenbank</n>
  </name>
  <item>ID_DATABASE_NEW</item>
  <item>ID_DATABASE_OPEN</item>
...
</menu>

Resource Type: Properties

IMatch uses properties to fill the property grids used for things like Folder and Category properties, the Info & Activity panel and some dialogs in the application preferences. In addition, properties are used for many of the internal configuration and persistence features in IMatch.

The <object_properties_table> node contains any number of <property_group> nodes. Each <property_group> node contains one or more <property> nodes.

Syntax

<property resid="RESID" desc="desc">
    <name xml:lang="lang">Name</name>
    <desc xml:lang="lang">Description</desc>
    <group xml:lang="lang">Group Name</group>
</property>
RESID The unique resource identifier for this command.
desc An optional description. This text is not translated.
lang The lang identifier. See Language Attributes for more information.
Name The name of the property. This name is displayed in the left column of the property grid.
Description The description of the property. This text is displayed in the help area under the property grid when the user selects the property.The description explains the purpose of the property, usage hints etc.
Group Name Properties can be put into groups, to keep related properties together in the grid. This is the name that is displayed for the group.

Example

<property resid="objectproperties.folder.numberoffiles">
  <name xml:lang="en">Number of Files</name>
  <name xml:lang="de">Anzahl der Dateien</name>
  <desc xml:lang="en">The number of files managed by (...)</desc>
  <desc xml:lang="de">Die Anzahl der von (...)</desc>
  <group xml:lang="en">Properties</group>
  <group xml:lang="de">Eigenschaften</group>
</property>

This property is used by the Folder properties grid in the Media & Folders view:

Folder Properties