As an example, we'll explain how to translate XXE messages to French[3].
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.
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.
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.propertiescancel
=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 | |
The ID of the message is " | |
English text of the message having " | |
Placeholder for the French text of the message having " | |
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/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:
applet_messages.properties 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/applet/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/select/Messages.properties com/xmlmind/xmleditapp/cmd/spreadsheet/Messages.properties com/xmlmind/xmleditapp/docset/modulardoc/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/linktype/Messages.properties com/xmlmind/xmleditapp/start/Messages.properties com/xmlmind/xmleditapp/vdrive/dialog/Messages.properties com/xmlmind/xmleditext/dita/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 dita.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), '\u
' (where XXXX
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 menu because the underscored letter is F
(i.e. _File
). In German, the 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.
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
".
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.
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.
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 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.
→ ,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
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 → .
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 → 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
Note that the above fr_translation.xxe_addon
does not contain any information about the author of the translation.
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:
" element. Therefore:email_address
">
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>
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.
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.
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 ReferenceunincludeAction.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}
| |
| |
| |
|