Keyboard Support

Contact and Search

Keyman.com Homepage

Header bottom

Keyman.com

On this page

Translating the Keyman Desktop User Interface

Translating the Keyman Desktop User Interface

Localization of the user interface is possible via editing a single XML file called locale.xml. The default locale.xml file is in the folder [Program Files]\Tavultesoft\Keyman Desktop Professional 7.0\xml\.

First steps to creating a translation

  1. Find the language code for your translation

    Use the ISO 639-2 or ISO 639-3 language code (we recommend using the ISO 639-3 codes as many Keyman keyboard layouts support languages not included in ISO 639-2!).

  2. Create a folder for the translated locale.xml file and copy the default locale.xml into it

    The folder should be called: [Program Files]\Tavultesoft\Keyman Desktop Professional 7.0\locale\langcode

File Format

The file is an XML file, with a few different elements:

  • Entity declarations: these are at the start of the file and define commonly repeated strings within the locale.xml file itself, for example, the name of the product.

  • Dialog elements: these define the size of a dialog box and, for some dialogs, the elements within the dialog.

  • String elements: every translatable string in the file.

Nearly all strings have identifiers (e.g. SKButtonOK for the OK button). We have three different types of strings in the file - plain, HTML and format strings:

  • Format strings often include %#:s or %#:d markers that are placeholders for parameters, and should be included in a translated string. The order of the markers in the translated string is not important.

    Example: <String Type="FormatString" Id="SKPackageAlreadyInstalled">A package with the name %0:s is already installed. Do you want to uninstall it and install the new one?</String>

  • Plain strings must be just that - plain text. These are all referenced by the XSL templates that make up the bulk of the Keyman Desktop user interface. You should not place any HTML tags in these entries as they will be stripped before display.

    Example: <String Type="PlainText" Id="S_ShortProductName">Keyman Desktop</String<

  • HTML strings can include tags - there are only a few of these, and they are flagged in the locale.xml file. The most obvious of these is in the Welcome screen text.

    Example: <String Type="HTML" Id="S_Splash_Button_Buy" AccessKey="B"><u>B</u>uy</String>

There is one exception to these formats - the strings on the tray menu do not have identifiers, but instead use the following format (note that the Caption attribute should not include the &amp; entity). You can even use these strings to translate the name of keyboard layouts in the tray menu!

Example:

<String Type="PlainText" Caption="Keyman Configuration...">localized &amp;text...</String>

The &amp; entity is used to mark hotkeys in menu items, labels and buttons. It can be used only with strings identified as formatted messages (these mostly start with SK) and with the Menu strings.

Hints on editing the file

First, edit the file's language information - SKUILanguageName, SKUILanguageNameWithEnglish, and SKLanguageCode. The SKLanguageCode should be the same as the language code you chose earlier. You will also see a String with id SKDefaultLanguageCode. For Keyman Desktop, this should remain "en" for all translations. When developing a custom product using the Keyman Developer Branding Kit, you may change your product's default language, and this would then entail changing SKDefaultLanguageCode.

Note

Any entries missing from the translated locale.xml will be retrieved from the default file.

Editing other files in the XML folder

If you find that you need to do more work on the user interface, you can always copy the other files from the default xml folder into your locale folder, and edit them directly. Note that the XSL file for each dialog (e.g. activate.xsl, or keyman.xsl) references other files - these other files must also be copied to the locale folder: [Program Files]\Tavultesoft\Keyman Desktop Professional 7.0\locale\langcode

Tip

The format and organisation of these files is complex. More details are available in the Keyman Developer Branding Kit and the Keyman Developer help files.