3. Procedure

3. Procedure
Prev		Next

As an example, we'll explain how to translate XXE messages to French^[3].

3.1. First step: extract English messages

C:\Program Files\XMLmind_XML_Editor\bin> translatexxe -m fr.txt

The above command creates a plain text file called "fr.txt" containing all XXE messages.

Important

Unless this is the very first time you translate XXE messages, you need to execute a command other than "translatexxe -m fr.txt". More information in Section 3.6, “When a new version of XXE is released, update your translation”.

By default, this text file is encoded using the native encoding of the platform (e.g. "windows-1252" for a West Europe PC running Windows) because it is assumed that the text editor you'll use to modify this file supports this encoding.

Tip

If you prefer, you can specify another encoding by using the "-e" option. Example:

C:\Program Files\XMLmind_XML_Editor\bin> translatexxe \
    -e ISO-8859-1 -m fr.txt

If you don't know the exact name of an encoding, specify something like "-e foo" and translatexxe will report an error and will list all supported encodings.

"Fr.txt" looks like this:

++++++++++com/xmlmind/xmledit/command/Messages.properties

cancel=Cancel
cancel=

### SelectById ---

SBI.selectId=Select ID
SBI.selectId=

SBI.referenceToUndefinedId=Reference to non-existent ID "{0}".
SBI.referenceToUndefinedId=
    .
    .
    .
EM.repeatAction=Repeat {0}
EM.repeatAction=

----------com/xmlmind/xmledit/command/Messages.properties
++++++++++com/xmlmind/xmledit/dialog/Messages.properties
    .
    .
    .

	Beginning of first section: messages contained in the `com/xmlmind/xmledit/command/Messages.properties` resource file. As a translator, you can ignore these markers.
	The ID of the message is "`cancel`".
	English text of the message having "`cancel`" as its ID.
	Placeholder for the French text of the message having "`cancel`" as its ID.
	A comment added by the author of the English messages. As a translator, you can ignore these comments.
	End of first section.
	Beginning of next section: messages contained in the `com/xmlmind/xmledit/dialog/Messages.properties` resource file.

3.2. Second step: translate English messages to French

++++++++++com/xmlmind/xmledit/command/Messages.properties

cancel=Cancel
cancel=Annuler

### SelectById ---

SBI.selectId=Select ID
SBI.selectId=Sélectionner un ID

SBI.referenceToUndefinedId=Reference to non-existent ID "{0}".
SBI.referenceToUndefinedId=Référence à un ID "{0}" qui n'existe pas.
    .
    .
    .
EM.repeatAction=Repeat {0}
EM.repeatAction=Répéter {0}

----------com/xmlmind/xmledit/command/Messages.properties
++++++++++com/xmlmind/xmledit/dialog/Messages.properties
    .
    .
    .

Open "fr.txt" in a text editor and start filling in the blanks. Be patient, because the initial translation will take you a few hours of a pretty tedious work.

You don't need to translate all the sections. In order to localize the whole GUI of XXE, it is sufficient to translate the following sections:

com/xmlmind/guiutil/Messages.properties
com/xmlmind/helperapps/Messages.properties
com/xmlmind/netutil/Messages.properties
com/xmlmind/util/Messages.properties
com/xmlmind/xmledit/cmd/Messages.properties
com/xmlmind/xmledit/cmd/attribute/Messages.properties
com/xmlmind/xmledit/cmd/character/Messages.properties
com/xmlmind/xmledit/cmd/edit/Messages.properties
com/xmlmind/xmledit/cmd/include/Messages.properties
com/xmlmind/xmledit/cmd/namespace/Messages.properties
com/xmlmind/xmledit/cmd/run/Messages.properties
com/xmlmind/xmledit/cmd/search/Messages.properties
com/xmlmind/xmledit/cmd/select/Messages.properties
com/xmlmind/xmledit/cmd/spell/Messages.properties
com/xmlmind/xmledit/cmd/table/Messages.properties
com/xmlmind/xmledit/cmd/validate/Messages.properties
com/xmlmind/xmledit/cmd/xsearch/Messages.properties
com/xmlmind/xmledit/edit/Messages.properties
com/xmlmind/xmledit/form/Messages.properties
com/xmlmind/xmledit/styledgadget/Messages.properties
com/xmlmind/xmledit/view/Messages.properties
com/xmlmind/xmleditapp/app/Messages.properties
com/xmlmind/xmleditapp/app/part/Messages.properties
com/xmlmind/xmleditapp/app/prefsheet/Messages.properties
com/xmlmind/xmleditapp/cmd/autospell/Messages.properties
com/xmlmind/xmleditapp/cmd/helper/Messages.properties
com/xmlmind/xmleditapp/cmd/object/Messages.properties
com/xmlmind/xmleditapp/cmd/process/Messages.properties
com/xmlmind/xmleditapp/cmd/spreadsheet/Messages.properties
com/xmlmind/xmleditapp/kit/Messages.properties
com/xmlmind/xmleditapp/kit/part/Messages.properties
com/xmlmind/xmleditapp/kit/prefsheet/Messages.properties
com/xmlmind/xmleditapp/start/Messages.properties
com/xmlmind/xmleditapp/vdrive/dialog/Messages.properties
com/xmlmind/xmleditext/docbook/Messages.properties
com/xmlmind/xmleditext/docbook/table/Messages.properties
com/xmlmind/xmleditext/xhtml/Messages.properties
com/xmlmind/xmleditext/xhtml/table/Messages.properties
docbook.properties
docbook5.properties
xhtml.properties
xxe_gui_messages.properties

In fact, certain sections (for example, com/xmlmind/xmledit/xsd/load which deals with validation of W3C XML Schemas) are very, very hard to translate and it's recommended not to translate them.

Note that the name of sections which really need to be translated are underlined using '##########' lines, which makes it easy distinguishing them from optional sections. Example:

++++++++++com/xmlmind/xmledit/command/Messages.properties
#########################################################
    ...

The translated message must be one-line long but you can fold long lines by typing a '\' immediately followed by a new line. Example:

badCommentChars="{0}",\n\
invalid character data in comment:\n\
cannot contain string "--" and cannot end with "-"
badCommentChars="{0}",\n\
caractères invalides dans un commentaire:\n\
ne peut contenir la chaîne "--" et ne peut se terminer par "-"

The customary Java™ escape sequences are recognized by the translatexxe utility: '\n' (newline), '\t' (tab), '\uXXXX' (where XXXX is the code of a Unicode character in 4-digit hexadecimal notation), etc.
The punctuation and capitalization of the original message must be respected.
Some messages contain one underscore character ('_') (e.g. "fileMenu.label=_File" in the figure below). Such messages are menu items and the underscore is located just before the letter which is used as the menu item mnemonic.
```
### File menu ---

fileMenu.label=_File
fileMenu.label=

newAction.label=_New...
newAction.label=

openAsTemplateAction.label=Open as _Template...
openAsTemplateAction.label=

openCopyAction.label=Open Cop_y...
openCopyAction.label=

openAction.label=_Open...
openAction.label=

saveAction.label=_Save
saveAction.label=

saveAsAction.label=Save _As...
saveAsAction.label=
```
Recommendations:
- The location of the underscore depends on the language used for the menu item.
  For example: in English, Alt+F opens the File menu because the underscored letter is F (i.e. _File). In German, the File menu is called Datei and the underscored letter should be D (i.e. _Datei).
- Do not underscore the same letter twice in the same GUI component (same menu bar, same menu, same dialog box, etc).
- Because this constraint can be really tedious to check, it is better not to use this facility at all rather than using it inconsistently. If you find underscoring menu mnemonics too tedious, do not underscore them at all.
A large number of messages contain strings {0}, {1}, {2}, etc. These are variables which are substituted by dynamically computed values just before the message is displayed to the user. The translated message must, of course, embed the same variables as the original message but the order of occurrence of the variables may be different if the syntax of the language requires so.

3.3. Third step: create the .jar file containing French messages

C:\Program Files\XMLmind_XML_Editor\bin> translatexxe -j fr.jar fr.txt

The above command creates an easy-to-deploy .jar file called "fr.jar" out of your plain text file "fr.txt".

Important

If your plain text file "fr.txt" has not been encoded using the native encoding of your platform, you must specify its encoding using the "-e" option. Example:

C:\Program Files\XMLmind_XML_Editor\bin> translatexxe \
    -e ISO-8859-1 -j fr.jar fr.txt

Translatexxe will guess the target language of your translation if you use a two-letter ISO code as the basename of your .jar file. In our example, "fr" is the two-letter ISO code of the French language.

Note that language variants such as "fr-FR" are not supported.

Tip

Nothing forces you to name your .jar file after the two-letter ISO code of your target language. But in such case, you need to explicitly specify to translatexxe which is this language by using the "-l" option. Example:

C:\Program Files\XMLmind_XML_Editor\bin> translatexxe \
    -l fr -j French_XXE_Messages.jar fr.txt

As usual, if you don't remember the ISO codes, specify like "-l foo" and translatexxe will report an error and will list all valid ISO codes.

3.4. Fourth step: test your translation to French

Copy fr.jar to one of the two addon/ directories scanned by XXE at startup time and start XXE.

If the language of the default locale of your platform is not the target language of your translation, you'll not be able to check what you have done. In such case, use Options → Preferences, General section, select the target language of your translation from the Locale combobox, then restart XXE. By doing this, you'll force XXE to use the locale you have chosen and hence, you'll be able to check your work.

3.5. Optional fifth step: package your translation for XXE add-on manager

By packaging your work as a .zip file for use by XXE add-on manager, you'll make it a snap for other XXE users to download and install your translation.

C:\Program Files\XMLmind_XML_Editor\bin> translatexxe -p C:\Inetpub\wwwroot fr.jar

Tip

Using the textual message file instead of the corresponding jar works fine too:

C:\Program Files\XMLmind_XML_Editor\bin> translatexxe -l fr \
    -p C:\Inetpub\wwwroot fr.txt

Notice the "-l fr", which is mandatory in this case, because translatexxe can guess the target language only from the basename of your .jar file.

The above command creates two files in directory C:\Inetpub\wwwroot\:

fr_translation.xxe_addon

An XML file describing your translation as an add-on, and pointing to fr_translation.zip (which is the file actually downloaded and installed by XXE add-on manager):

<a:addon xmlns="http://www.w3.org/1999/xhtml"
  xmlns:html="http://www.w3.org/1999/xhtml"
  xmlns:a="http://www.xmlmind.com/xmleditor/schema/addon"
  location="fr_translation.zip">

  <a:category><a:translation /></a:category>
  <a:name>French translation</a:name>
  <a:version>3.1.0</a:version>
  <a:date>2006-01-13</a:date>
  <a:xxeVersion>3.1.0+</a:xxeVersion>

</a:addon>

In order to download and install your translation, an XXE user will have to add the URL of the above fr_translation.xxe_addon file to the list found in the Preferences dialog box, Install add-ons section and then execute Options → Install Add-ons.

The Preferences dialog box step is just needed the first time your translation is installed. After that, if you have chosen a stable public URL for fr_translation.xxe_addon, suffice for the user to execute Options → Install Add-ons each time you'll upgrade your translation.

fr_translation.zip

A Zip file containing everything needed by XXE add-on manager, which is:

C:\Program Files\XMLmind_XML_Editor\bin> unzip -v C:\Inetpub\wwwroot\fr_translation.zip
Length   Method  Size  Ratio   Date   Time  Name
-------  ------  ----- -----   ----   ----  ----
      0  Defl:N      2   0%  01-13-06 17:04 fr_translation/
  50317  Defl:N  39518  22%  01-13-06 17:04 fr_translation/fr_translation.jar
    414  Defl:N    225  46%  01-13-06 17:04 fr_translation/fr_translation.xxe_addon
-------          -----  ---                 -------
  50731          39745  22%                 3 files

3.5.1. Signing your work

Note that the above fr_translation.xxe_addon does not contain any information about the author of the translation.

Important

This may be a problem if you intend to share your work with other XXE users by the means of the upload form found at http://www.xmlmind.com/xmleditor/_contribute/. In such case, the upload form will reject your add-on unless it is properly packaged as a .zip file and its .xxe_addon description contains a a:author element.

This glaring omission can be fixed by using the "-a" option. Example:

C:\Program Files\XMLmind_XML_Editor\bin> translatexxe -a "Jean-Luc Picard" \
    -p C:\Inetpub\wwwroot fr.jar

The argument of the "-a" option may be plain text or (properly escaped, ``inline'') HTML starting with prefix "<html>". Example:

C:\Program Files\XMLmind_XML_Editor\bin> translatexxe \
    -a "<html><a href='mailto:jlp@sttng.tv'>Jean-Luc Picard</a>" \
    -p C:\Inetpub\wwwroot fr.jar

The above command adds an author element to fr_translation.xxe_addon.

<a:author><a href='mailto:jlp@sttng.tv'>Jean-Luc Picard</a></a:author>

If you pass the "-a" option an argument starting with "mailto:", it is smart enough to guess that you intend to specify an HTML "<a href="mailto:email_address">" element. Therefore:

C:\Program Files\XMLmind_XML_Editor\bin> translatexxe \
    -a mailto:jlp@sttng.tv -p C:\Inetpub\wwwroot fr.jar

will add:

<a:author><a href='mailto:jlp@sttng.tv'>jlp AT sttng DOT tv</a></a:author>

3.6. When a new version of XXE is released, update your translation

Each time a new version of XXE is released, hopefully, you'll want to update your translation. For this, you need to recreate a new "fr.txt" out of XXE .jar files and your own "fr.jar". The command below does this:

C:\Program Files\XMLmind_XML_Editor\bin> translatexxe -m fr.txt C:\temp\fr.jar

Browse the new "fr.txt" and find which English messages have been added since the last time you translated XXE. These new English messages are followed by empty placeholders. Then repeat second to fourth step and optionally, fifth step.

Important

Never work on your original "fr.txt". Always recreate a new "fr.txt" out of XXE .jar files and your own "fr.jar". That is, the reference here is XXE code and your "fr.jar". "Fr.txt" is just a temporary file which should be deleted after it has served its purpose.

3.6.1. Updating your translation after a major release of XXE

A major release of XXE generally means that its code, and thus the messages to be translated, have been heavily reorganized.

Simply using something like "translatexxe -m fr.txt C:\temp\fr.jar" works fine but also means that you'll loose hundreds of messages you have already translated because, due to the reorganization, these messages have been moved from one section to another.

Fortunately there is a solution to this problem: use option "-ms" (make suggestions) instead of plain "-m". Example:

C:\Program Files\XMLmind_XML_Editor\bin> translatexxe -ms fr.txt C:\temp\fr.jar

Using this option generates a message file which looks like this:

unincludeAction.label=_Untransclude Reference
unincludeAction.label=
...

searchMenu.label=_Search
searchMenu.label=_Rechercher
...

confirm=Confirm
#PROBABLY:
confirm=Confirmer
...

cannotDeleteFile=cannot delete file "{0}"
#SUGGESTIONS:
cannotDeleteFile=ne peux supprimer le fichier\n\
"{0}"
cannotDeleteFile=Ne peux supprimer\n\
"{0}":\n\
{1}

	`unincludeAction.label` is a new message that needs to be translated. Nothing new compared to what's generated using option "`-m`".
	`searchMenu.label` is a message that you have already translated to "`_Rechercher`". Here too, nothing new compared to what's generated using option "`-m`".
	`confirm` is a message that you have already translated and its translation is probably^[4] "`Confirmer`". You need to check this translation and then remove the "`#PROBABLY:`" comment line.
	`cannotDeleteFile` is a message that you have already translated. There are several possible translations for it that follow the "`#SUGGESTIONS:`" comment line. You need to check the suggested translations, remove all translations but one and then remove the "`#SUGGESTIONS:`" comment line.

^[3]This is just en example because XXE has already been translated to French.

^[4]In fact, almost certainly.

Most message translators will want to automatically delete all "#PROBABLY:" comment lines and spend their time checking the suggestions that follow the the "#SUGGESTIONS:" comment lines.

Prev		Next
2. How does it work?	Home	4. Command line options