Typing around the world

Translating the Keyman Desktop UI - again!

I was asked via email this morning about the changing locale.xml file format between build 223 and build 224 of Keyman Desktop.  I had meant to write an update on this blog for my previous post about the file format - so here it is.

We reworked the locale.xml file format in build 224 to make it more consistent and eliminate some issues with extensibility.  I believe the new format is more logical - here's an overview:

<?xml version="1.0" encoding="utf-8"?>
<Locale>
  <String Type="PlainText" Id="S_ShortProductName">Keyman Desktop</String>
</Locale>
<Dialog Id="DownloadKeyboard" Width="600" Height="400">
  <footerheight>40</footerheight>
</Dialog>

Each string has a type of PlainText, HTML, or FormatString, according to how it is used.  PlainText cannot contain markup of any kind; HTML can.  FormatStrings are used mostly in dialog boxes and other messages, and cannot contain markup, but often contain parameters such as %0:s or %1:d.  These parameters can be put in any order in the output string - and can even be repeated.

We also have some new information - each HTML-based dialog in Keyman Desktop Configuration has an entry in the file that specifies its pixel width and height, and optionally some internal dimensions as well.  In the example above, the footerheight for the DownloadKeyboard dialog is given as 40 pixels.

That's all there is to the format...  Of course the new file format is wonderful and is going to solve the world's problems, but for anyone who already did a translation, that's not going to make them happy!  (Vincent?)

So, I wrote an XSLT template to translate the build 223 format to build 224 format.  The template and some wrappers to execute it are available at: www.tavultesoft.com/support/files/.  There are two wrappers for the template (or you can use your own favourite XSLT processor):
* An IE only web page - convertlocale.html  (uses ActiveX to access Msxml2.DomDocument)
* A Windows Scripting file - convertlocale.js

To run convertlocale.js, start a command prompt and type:

cscript [/nologo] convertlocale.js <infile.xml> [<outfile.xml>]

If no outfile is given, then the output is written to stdout.

If you have any issues with the conversion, please let me know.

Translating the Keyman Desktop UI

The Keyman Desktop 7.0 Beta 2 UI is now both customizable and localizable.  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 keyboards 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 format is straightforward - most strings have identifiers (e.g. SKButtonOK for the OK button).  The identifier of the string is the XML tag name.  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.
• Plain strings must be just that - plain text.
• 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.

The only exception is the strings on the tray menu, which do not have identifiers, but instead use the following format (note that the Caption attribute should not include the &amp; entity):

    <Menu Caption="Keyman Configuration...">localized &amp;text...</Menu>

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.

Editing the File

First, edit the file's language information - SKUILanguageName, SKUILanguageNameWithEnglish, and SKLanguageCode.

<!--   The name of the UI language, localized -->
<SKUILanguageName>English</SKUILanguageName>

<!--   Show the name of the UI language, localised, with English name in parentheses (this message is used when the user gets stuck in a strange UI language) -->
<SKUILanguageNameWithEnglish>English</SKUILanguageNameWithEnglish>

<!--   The language code for the current translation -->
<SKLanguageCode>en</SKLanguageCode>

Note that any entries missing from the translated locale.xml will be retrieved from the default file.

Editing other Files

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 an xml subfolder of 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 xml folder:

  [Program Files]\Tavultesoft\Keyman Desktop Professional 7.0\locale\langcode\xml

The format of these files is somewhat more complex; I may talk about them in the future.  But feel free to play around and edit!

Finally...

The Keyman Developer user interface is also localizable (not 100% ready yet), but it primarily uses gettext, with a small amount of translatable XSLT.  We will include the gettext .pot template in the release of Keyman Developer.

The usual beta warning applies - these file formats are not necessarily 100% stable, and some changes may occur.  However, we expect only that more strings will be added to the final locale.xml, and we don't expect structural changes.