Localization Guide

The actual "how to" for localizing ClipMate.

(Update: As of Feb 2 2006, it applies to ClipMate 7)

Contents

• Tools & Methodology
• Polyglot
• IniTranslator
• PGRecon
• Files To Translate (source files)
• Other Tools
• Switching Languages
• Complete Download Listing

Tools & Methodology

After consulting with other developers, we've determined that a simple approach to translation is going to work out best for us.  Instead of a binary translation with big, complicated, and expensive tools, we're going with an "ini-file" translation, using a translation loader called Polyglot by Balmsoft.

Polyglot has no GUI, but it does work well with an free, open-source ini translation GUI called IniTranslator, which supports dictionary translations.  You can use that (we'll tell you how), or you can use other tools such as Notepad or Excel.

Here's a sample from the translation file (ENGLISH.LNG)

[TfrmClipMateHidden]
act_ViewOnTop.Caption='Always On Top'
act_HelpTutorial.Caption='Tutorial'

And translated to French:

[TfrmClipMateHidden]
act_ViewOnTop.Caption='Toujours visible'
act_HelpTutorial.Caption='Didacticiel'

Here's how it looks within IniTranslator

Watch a Flash tutorial showing a simple translation using IniTranslator. This will give you a good overview of the process.

Let's look at the different aspects of the translation.  Each element has a "section", which is marked as:  [section]  in the file.  That tells PolyGlot which form (screen) that the translation refers to.  The individual button, radio box, etc., captions and menus for a given screen are related under the section, typically starting with "Tfrm", and the rest if the internal name of the screen. Like TfrmClassic, TfrmExplorer, etc..  Then there are the "global" sections TfrmMain (main, hidden form with "master" menus and action lists, and the [resourcestrings] section which is a list of messages, captions, titles, etc., used throughout the program.

Then you've got the "name" of the element, which is listed to the left of the "=" (equal) symbol in the translation file. This identifies the individual control or resource ID of the text.  And finally, there's the string itself, which is to the right of the "=" symbol in the translation file.  The IniTranslator loads this string either into the "Original" or "Translated" column, as it actually works with two files at once. If you're working with the English.LNG file, that would be on the left. And you're translating to French, then French.LNG would represent the fields on the right.

Notice how the section name and item name ([TfrmMain].act_ViewOnTop.Caption) appear in the IniTranslator screenshot above. Look in the grey area, beneath the toolbar.  This shows you were this string resides, within ClipMate.

Notes about the tools:

Polyglot

• There is nothing to buy, and nothing for you to install.  Polyglot is built into ClipMate and will use .LNG files, if present in the "language" directory, typically c:\program files\ClipMate6\Language
• The PolyGlot format is in the form of:  name='some string'
  Our PolyGlot Plug-In for IniTranslator handles then quote removal and insertion.  But it won't cope with single quotes in the data.  So I should have said:  It will not cope, instead of It won't cope.  I as the developer, and you as the translator, need to avoid the use of the single-quote (apostrophe) character in our strings.

IniTranslator

• Download the free IniTranslator from sourceforge.  (Complete download listing is at the bottom of this page).
• Download and install the PolyGlot Translator plug-in for IniTranslator. 
• With the plugin, you're always importing and exporting. Never use Open/Save.
• The Import will import both the original (English) and translation (ex: French) at the same time, loading each file into its respective column in the translator. Your first time using it, there won't be a translation file. So just load the English.Lng. When you're ready to save, export the translation (ex: French.lng). The next time you load, you'll Import both files: English.Lng as the Original, and French.lng (or whatever) as the translation.
• The Ini Translator home page is at http://initranslator.sourceforge.net  It is distributed under MPL 1.1, and we have therefore made the source code for our plug-in available.
• v0.5 of our "PolyGlot Plug-In" gives you the option of "zeroing-out" the resource IDs as you import the files. This can be handy if you are continuing from translating a previous ClipMate version, and have saved the translation files in IniTrans (.ini file) format.Use the PGRecon after exporting, to put the IDs back the way they need to be. 

PGRecon

• Polyglot gets some of its speed by using resource IDs to index the resource string section of the translation file.  Unfortunately, the compiler (Delphi) re-assigns these strings every time we re-compile the program, so the resource strings need some "fixing" from one version to the next.  For example, Suppose you translated this string in ClipMate 6.5.04:
  • 64638_arm_R_ARM_ERROR_ACCOUNT_EXPIRED='Key Expired'
    to
    64638_arm_R_ARM_ERROR_ACCOUNT_EXPIRED='Le Key est Expiree!'
  • Now a new version comes out, and the original English string
    has changed its ID!!!! Now it's 64699!
    64699_arm_R_ARM_ERROR_ACCOUNT_EXPIRED='Key Expired'
  • But your translation still says:
    64638_arm_R_ARM_ERROR_ACCOUNT_EXPIRED='Le Key est Expiree!'
  • You need to convert the ID from 64638 to 64699.   Otherwise strange things will happen, and you may get a "localization file out of date" message.
  • The PGRecon (stands for PolyGlot Reconciliation) tool will correct your file for you, by comparing your translation against a current English.Lng, and fixing your string IDs to match, but keeping your translated strings intact.
• Screenshot - see what I'm talking about
• Download (see the download list)
• Installation - Just make a directory, unzip the files, double-click to run
• Usage:
  • English LNG: Points to the English translation that matches the version of ClipMate that you're targeting  (usually the latest).
    ex: c:\program files\clipmate7\language\English.lng
  • Trans IN: Your old translation.
    ex: c:\program files\clipmate7\language\old_French.lng
  • Trans OUT: The new (fixed) file to be written out.
    ex: c:\program files\clipmate7\language\French.lng
  • Press GO: The resource strings section is read from the English.lng, and is used as a reference to map the old translation strings to the new IDs. Only the [ResourceStrings] section is actually altered. The rest of the sections (forms, such as frmAbout, frmMain, etc.) just pass right through.
  • Errors: Anything that was in your translation but couldn't be located in the new English.lng, is noted in the Errors section. It may be normal to find a few lines here, if items have been removed from the original source, or converted from the ResourceString section into other areas.
  • TIP: Before using, make a copy of your old .lng, and rename it to old_something.lng, where "something" is your language name. This is to avoid overwriting the input with the output, which it won't let you do anyway.

Files To Translate

• ClipMate Strings - Just install either of the multi-language installers, and that'll place "english.lng" into the "language" directory beneath where ClipMate is installed - typically c:\program files\clipmate7\language  If this directory does not exist already, you'll need to create it first. 
  NOTE: if you use the regular "english-only" installer, you'll have a "stub" version of english.lng. You need the multi-language version to get the full version of english.lng.
  • Translate English.Lng into the language of your choice, using IniTranslator or the tool of your choice.
• Web Pages - In the translation source file (above), you'll find an XML file called XLATE.XML. This is the basis for the content found on pages like this French page.  Just translate the text within the tags.
  • Translate XLATE.XML into the language of your choice, using any text editor.

  Setup - we use the popular Inno Setup program which already includes most (all?) translations. There are a few ClipMate-specific messages that need translation, and we've included those in XLATE.XML as well, in the <SETUP> section.

  • Translate XLATE.XML into the language of your choice, using any text editor.

  Ordering Information - we use plimus.com for international ordering due to their excellent customization and localization capability. Most of the ordering is already translated for us, but there are a few more strings that need translation, and those are in XLATE.XML as well. 

  • Translate XLATE.XML into the language of your choice, using any text editor.
• Help File - We're using Help & Manual, which supports XML Import/Export. You can translate the exported XML with any text editor.  Or, if you have a helpfile translation tool that can translate a .CHM file, you can use that on the ClipMate.chm file that is in the regular ClipMate download.  Or you can edit the HTML version of the help, by editing the .htm files.  ClipMate is designed to integrate with the .CHM (Windows HTML Help) style help, but if that's not possible, providing even a partial translation as plain HTML, will be a big help.
  • Help & Manual Project Files.

Others

• You can also use Notepad, any text editor, Excel, etc..  But the end result has to be in the same format that you start with. 

Switching Languages:

ClipMate doesn't yet automatically select a translation file based on the Locale of the computer it's running on.  So to switch languages, go to Tools | Languages, then pick a translation from the menu.  (But once your language pack is included in a multi-language installer, it WILL pre-select the langage at installation time.)

Although some elements may change immediately, a re-start is required before the translation will have full effect.  On the Language/Fonts screen, you'll see several font selections, which are described in the next section.

Complete Download Listing