Localization tips for OpenOffice.org 2.0

+ + + + + + +

+ +

+ Localization tips for OpenOffice.org 2.0

+ Javier SOLA - + www.khmeros.info - Last edited + 05/04/2005 - + Top

+ This file contains work in progress.

+ The contents of this pages might (and probably + will) change often without warning

+ This page constains information received + in the mailing list or directly from the developers.

+
+ Wizard localization
+
+ Database Module - Should the field names in the + Database creation wizards be localized
+
+ Math Module - Some Strings have localization restrictions
+
+ There are lots of strings that look very much like field names in + sc/source/ui/src

+ Wizard + localization

+ Warnings:

+
+ You have to be very careful editing wizard template documents, + because if you do something wrong the wizards may crash or do not + work properly.
+
+ Never open template documents directly by File->Open. You have to + use File->Templates->Edit and navigate to the files and open them, + otherwise you will lose important template document information + (e.g. the description of the template)
+
+ Do not change the names of template files for the wizards, because + the wizards need some elements of the filenames to work. +

Some + general important tips on editing the template files for the letter and + the fax wizard (most of this is also true for all other template files): + +

+
+ Never translate the strings <First Name> <Company> and so on in the + address field. The wizards looks for those strings and the user will + not see them. In most cases strings in <> should not be translated. +
+
+ Never change the name of any of the sections or styles in the + template, the wizard needs the correct english section and style + names.
+
+ You have to translate the elements of the templates second page + also. For this you have to somehow force the document to have a + second page (e.g. by a manual page break), translate the strings and + then delete that second page. The document still contains those + texts because they are in the headers.
+
+ Do only change/translate and not delete any of the placeholders or + user fields in the templates
+
+ Change the page format and all templates language settings (e.g. in + the styles) to the usual ones of the language you translate for +

+ Unfortunately, there is no possibility to change the font used for the + yellow help windows/boxes. Those windows always use the standard UI font + of your system. On StarOffice this is the installed soui.tff font. I do + not know which font is taken on your system for this if you use + OpenOffice, because OOo is not shipped with a special UI font. The UI + font usage is then handled by the font fallback mechanism in OOo. If + this font does not contain the characters you need you get those little + empty squares - an empty square means that the correct symbol is not in + the font. This may also help you to find out which font is used: The + font used for the yellow boxes is the same as for the menus and dialogs + and so on. +

+ There is no need to translate the dialog + window, that appear when you open a file like bus-elegant_l. If you use + File->Templates->Edit you will not get this dialog and the users will + also never see them because the letter wizard template files are opened + by the letter wizard itself. +

+ + Database Module - Should the field names in the Database creation + wizards be localized

I + asked the developer and he says, because we support so many different + databases, please only use a-z characters, no umlauts or hyphens, etc.

Plus + some extra info on these strings:

+ PRJ officecfg

+ Filename registry\data\org\openoffice\Office\TableWizard.xcu

These + strings appear in the Table Wizard in list boxes.

No + spaces are allowed because they are field names.

+ *important* +

Every + 2nd string is a "short name" or short form of the full length string + before it.

The + short names _cannot + exceed 10 characters_ (due to + database restrictions).

+ Therefore the translation cannot exceed 10 characters either. +

(For + CJK: You can use 10 double byte Asian characters.)

+ Math + Module - Some Strings have localization restrictions

+ Rules regarding the l10n of some of the + strings that have caused bugs in some languages in the past, and may + still be causing problems. +

+ In the math module 66 strings need to + comply to some rules, otherwise some functionality in math is broken. + +

+ The 66 strings have some common "Resource + information":

+ PRJ starmath

+ Filename source\symbol.src

+ GID RID_UI_SYMBOL_NAMES

+ Type itemlist

The + strings are names for the greek characters and some extra symbol names. +

The + rules for this group of 66 strings are:

+
+ The first character has to be an alphabetic character (any + character set allowed).
+
+ All following characters must be alphanumerical characters (any + character set allowed) or the ASCII decimal dot (a dot from a + different character set or with a different character code is not + allowed).
+
+ The above rule especially does not allow for spaces or underscore of + any kind to be used.
+
+ An ASCII dot should not be followed by another one.
+
+ Case does matter and may be used (That is "alpha" may be used to + denote the lowercase greek character and "ALPHA" for the capitalized + one).
+
+ No double entries allowed

A + recommendation for Asian languages is to use the same string as the + english one, since there is no uppercase or lowercase.

+ Another recommendation is on the use of word separation. In eqch + language only one method should be used. Methods are:

+
+ Use no method at all: strictlygreater
+
+ Use one decimal dot: strictly.greater
+
+ Use capitalized letters: strictlyGreater

Examples:

Good:

-----

alpha

ALPHA

strictly.greater

strictlyGreater +

Not allowed:

------------

strictly..greater

9trictly

strictly_greater

strictly greater

strictly-greater

+ There are lots of strings that look very much like + field names in sc/source/ui/src

Q. Besides the wizards in In POTs made from + contents of sc/source/ui/src, there are lots of strings that look very + much like field names (or function names). The whole block of strings + around ~800-~1500 (financial calculations and other functions) + seems to run like this: .1 = function + description, .even_number = + function (or parameter) name, .odd_number = function (or + parameter) description.

So, I'd like to make sure, what of these is + translatable, and what isn't?

A. All of sc/source/ui/src/scfuncs.src is + translatable, with the exception of the ExtraData structs of course, + which isn't exported to POTs anyway.

You identified the strings of + RID_SC_FUNCTION_DESCRIPTIONS* correctly, first string of a function is + it's description, then alternating follow a parameter's name and it's + description. However, the parameter names should be consistent and + identical for identical functionality, e.g "Database field" for + all parameters that are used as a database field, or "Number" for + any number. Usage could have been defined in the glossary of your + language. What looks like function names in + sc/source/ui/src/globstr.src, for example RID_GLOBSTR.STR_* names SUM, + COUNT and so on, should be identical to the real function names used in + sc/source/core/src/compiler.src for consistency, but isn't necessary for + functionality. These names are offered to the user to choose from in + some dialogs and are mapped to the real functions then.

The function names used in formulas and in the + function pilot are defined in sc/source/core/src/compiler.src and have + the constraints that they can't contain spaces or symbols or other + punctuation characters than dot ('.') or underscore ('_'); letters and + digits are fine (must start with a letter), the definition of letter + here includes accented characters, CJK characters, and so on.

+ +

+ + + + + + +

+ +

+ Translation of the + OpenOffice 2.0 program software

+
Of the OpenOffice software + itself (messages)

+ The translation of the OpenOffice software + can be easily done using simple specialized translation editors that + are also Open Source. Learning how to use one of these editors + should not take more than half a hour.

+ The translation can be equally done in either the + Linux or the MS Windows environments.

+ The messages that appear different parts of + OpenOffice (menus, screens, error messages) have been extracted from + the source and placed in files that are easy to handle and to + translate. These files are called "PO files" and their format is + used for the translation of many Open Source applications.

+ A PO file is just an structured list of messages that + contains, for each message, the English original message text (msgid) + and the translation to the target language (or an empty string that + will be filled by somebody with the translation of the message). If + the file still does not have any translations (all the translated + string are empty), it is called a PO template file, and usually + given the .POT extension, instead of the traditional .PO extension + of PO files. Once a translator starts to translate a .POT file, he + will save it with the .PO extension. PO are text files in UTF-8 + format, so they can also be seen and modified with a normal text + editor that can handle UTF-8 format (most text editors can).

+ But let's start from the beginning, step-by-step.

+ 1) You need to know exactly what version of + OpenOffice you want to translate.
+
If you are + not sure about what version to translate, it is always a good + idea to ask in the + dev@l10n.openoffice.org mailing list. Most often you will + translate the latest stable version of the program.

+ An exception of this rule is when there is a new + important milestone coming soon, in which case you will have to + translate the upcoming version. For example, at the time this + document is written, version 2.0 of OpenOffice is expected + within the next four to six months, and it is no longer + interesting to attempt translation of a 1.1x version, even if + they are the last stable versions.

+ If the inclusion of your language in OpenOffice + requires changes in the code (patches, locale file, etc.), you + will have to work towards the next version that will be released + within the branch that you want to translate. For example, if + the last released version is 2.1, this means that 2.1 is closed + (no changes can be done for 2.1), so you can only work towards + 2.2, if the necessary changes are integrated in 2.2. As 2.2 PO + files will probably not be available when you start, you can + always translate the PO files for 2.1, and then, when the PO + files for 2.2 become available, you can upgrade to 2.2 (use the + information stored in the 2.1 PO files to automatically fill the + identical messages in the PO files of 2.2), translate the few + additional messages that there might be in 2.2... and follow the + process explained below.
+

+ 2) Get the POT files and the GSI format file for that + version

+
The file + that you need for the translation are under:

+ + ftp://ftp.linux.cz/pub/localization/OpenOffice.org/devel/ + +

+ If you point your browser to that address, you + will find a folder for each active branch of OpenOffice (each + active OpenOffice project). Each branch has a name or number: + 645 for version 1.1.x of OpenOffice and 680 for 2.x. You should + get the files from the folder that correspond to the version + that you want to localize. If you are working on the latest + branch, you should look into the directory POT. In case of + doubt, ask in the list.

+ In whichever directory you look, you will find at + least two files:
+
+
A tar + file that contains all the POT files (PO templates)
+
+
The en-US.sdf + file.
+
+
You need to + download both of them. For the moment you do not need the en-US.sdf + file, but you will need it when you finish the translation and + need to convert the PO files to the OpenOffice format. It is + important that - in that process - you use the version of the + en-US.sdf file that is associated to the POT files that you + downloaded. That is why we ask you to download it, label it and + store it now, to avoid confusion later.
+

+ 3) Get a PO file editor, if you do not already have + one.

+
There are PO + editors for both Linux and Windows, you should use the one that + best fits the working environment of the translators that will + be using the editor.

+ In Linux the most used PO editor is probably + KBabel, + associated to the KDE user interface (*** REVIEW *** describe + KBabel).

+ In the Windows environment, + poEdit does the job quite + well. Besides being simple and doing everything that is expected + of a PO file editor, it has its own "translation memory": each + time a PO file is saved, the editor automatically saves all the + messages of that file and their translations in a database (this + database is your translation memory). When you open a new PO + file (normally this happens when you are upgrading to a new + version), you can ask the editor (just click a button) to search + in the translation memory database for the messages that are in + that PO file, and - if it finds any - to place the translation + in the correct place of the PO file.
+
+ poEdit also runs on Linux, and we do + recommend it as a good tool.
+
4) Translate.
+
Translating + the OpenOffice suite is not an easy task. OpenOffice 2.0 contains + roughly 22.000 messages. It is not too far off-the-mark to + consider that it requires a full-time translator for about 12 months + to complete the task, given that he has the right glossary.

+ Prior to starting the translation of OpenOffice, + you should have a glossary of computer terms (user-interface + terms) for the target language, otherwise you will be stopping all + the time to figure out specific translations for different + terms, and your translation will be inconsistent, specially if + it is done by several translators working together (which is a + good idea). Besides your computer terminology glossary, you will + also need mathematical, statistical and accounting + terminologies, to translate many names of functions used by + Calc.

+ You should consider (depending on your + resources), how many translators you want to assign to the task + of translating the OpenOffice software. This will depend on the + overall task that you set for yourself. Will you also translate + the help? Will you translate documentation? Training materials? + You should also consider how long you want your translation to + take.

+ In our experience, in the case of translation + being done professionally, a team of three or four + translators can work very well, having each team member + translate his part and double-check translations made by another + team member. With a three person team translation of the + software can be accomplished in four months (of course it can be + three or five, depending on speed, enthusiasm and the quality of + the glossary, but four is a good reference to start with).

+ You should also develop translation guidelines + for translators, regarding length of messages, how you should + translate certain things, how to deal with variables, etc. +
+
+ Variable names in OpenOffice have several + different ways of being represented. As far as we know, + variables might take one of these forms:
&VariableName;
+%VariableName%
+%VariableName
+$VariableName$
+$(VariableName)
+${VariableName}
+($VariableName)
+#VariableName#
+$[VariableName]
+
+ Variables are place-holders for dynamic + information (the name of a file, a program, some name) to which + the message you are translating makes reference. The Variable + should always be in the translated sentence in the right place + for that information. You should never translate the name of + a variable. +
+
+
5) Installation + of Translate Toolkit
+
It is now + time to install the Translate Toolkit in your + computer (either Linux or Windows). These tools are used to + check your messages and to convert your PO files pack to a + format that is clearly understood by the OpenOffice software.

+ (*** REVIEW *** installation of Translate + Toolkit)
+
6) Check your PO + files
+
Once you + have finished translating and made a back-up copy of your PO files, it is a good idea to + check if the are correct is some technical aspects, such as + making sure that if a given variable is in the original string, + the same variable is also in the translation, or that if some + message starts or finishes with a blank space, so that the + translation, having similar capitalizations in original and + translation (for scripts that have capital letters), etc...

+ The checking process consists on checking your + translated PO files for inconsistencies or possible problems, + filter to new files all the problematic translations, work on + them, and then merge them back into the original files. As + complicated as this might sound, it is quite simple, by using + the Translate Toolkit.

+ a) Filtering

+ The tool from the Translate Project that does + this check is called POFILTER, and it should be used from + the console (Linux) or from the command prompt (Windows). We + assume that you have followed the instructions in the prior + section and that the PO tools correctly installed in your + computer.

+ POFILTER analyses a whole tree of PO files, + searching for possible errors and problems in the PO files one + by one. It creates as output another tree, identical in + structure to the tree in which your PO files are, and in this + new tree, in the same place that the original PO files in the + first tree, it creates PO files in which only problematic + messages are included. For example:
+
+
+
If in + your PO file tree you have a file called po/sfx2/source/menu.po, + and that file has a problem in one of the message.
+
+
And you + run POFILTER, specifying "checks" are your output tree.
+
+
A file + with path checks/sfx2/source/menu.po will be created, which + will include only messages from the file po/sfx2/source/menu.po + which POFILTER considers that you should check again by + hand.
+
+
In order to + run POFILTER, you should use in the command line the following + syntax:

+ pofilter --openoffice <your-po-file-tree> + <tree-where-checks-will-be-stored>

+ Of course, we assume that the pofilter + program is in your path or that you write the whole path for it. + For example, as in the case above, all your files are in a + directory called po, and you want the output to go to a + directory called checks, and (for this particular + example) we assume that you are working on Windows and that your + Translate Project tools are in the \dev\tools\ directory, you + should use the command:

+ \dev\tools\pofilter --openoffice po + checks

+ Sometimes - depending on your language - POFILTER + can give you a lot of false positives (find as possible errors + translations that are correct). POFILTER, for example checks by + default if capitalization in the original and in the translation + is similar. This - of course - does not apply to Indic + languages, which have no capital letters. Also, by default, + POFILTER checks if all messages have been translated. In some + cases you might do test or partial transaltions, so you do want + this test deactivated. +

+ IT is possible to indicate to POFILTER which test + you want to deactivate when using it. The most useful tests that POFILTER + uses are:

+·     + +escapes             - Checks +whether escaping is consistent between the two strings
+
+·     +endpunc            - Checks +whether punctuation at the end of the strings match
+
+·     + +unchanged          - Checks +whether a translation is basically identical to the original string
+
+·     + +untranslated        - Checks +whether a string has been translated at all
+
+·     + +variables             - Checks +whether variables of various forms are consistent between the two strings
+
+·     + +whitespace         - Checks +whether white spaces at the beginning and end of the strings match
+
+
+
+To see a complete list of tests, please run pofilter with the -l option, +or go to the Translate Project Reference Documentation.
+

+ The excludefilter option is used in the command + line to exclude specific filter(s). As an example, if you want + to run POFILTER while deactivating the capitalization check and + the check for untranslated (empty or identical to the original), + you should use the command (following with the same example):

+ \dev\tools\pofilter --openoffice --excludefilter=untranslated + --excludefilter=unchanged --excludefilters=simplecaps po checks

+ b) Correct

+ Once you run POFILTER, you need to use your PO + editor to check all the files that are in the checks + directory, until you are sure that they are all correct.
+
+ c) Merge corrected messages back.
+
+ The next step is re-integrate the corrections in + the original PO files. This is done with the Translate Tool + program POMERGE. Before you do it, we recommend that you make a + new back-up copy of your po and checks + directories, then you can run:
+
+ pomerge -i <folder-with-corrected-files> -t + <folder-with-original-incorrect-po-files> -o + <folder-for-corrected-files>
+
+ If we use that we have been following, and we + want to just over-write the incorrect files in the po + folder with corrected files, we should use the command:
+
+ \dev\tools\pomerge -i checks -t po -o po
+
+ At this point you can just go ahead, or run again + pofilter, to see if all the problems that you had + detected have disappeared. If pofilter gives new positives, you + have to repeat the whole checking process again.
+
+
7) Create an + OpenOffice file that contains your translations
+
+ Now the files are ready to be converted back to a + format that OOo likes. You can do this conversion using the + po2oo tool from Translate Project . For this you need to + remember were you put the original en-US.sdf file that you + downloaded together with the PO files, because you need to + include the path to it in the po2oo command. +
+
+ In order to create, an OpenOffice file, you also + need to indicate what will the the locale for the transaltion + you are doing. You must include in the command the name fo the + locale for which you are translating.
+
+ po2oo -i <folder-with-po-files> -t en-US.sdf -o + <name-of-GSI-format-file> -l <Locale-name>
+
+ In our example, as we are translating for Khmer, this could look like:
+
+ \dev\tools\po2oo -i po -t en-US.sdf -o + oo-2.0-km-GSI.sdf -l km
+
+ which would produce as output the file + oo-2.0-km-GSI.sdf, the final product for which you have been + working for all this time, and which will be integrated in the + sources of OpenOffice.
+
+
8) Create an + issue in OpenOffice

+
+ Create an issue for the + Localization (L10n) project. To submit + an issue you first need to login into the OpenOffice website, then + hit File Issue on the left hand + menu go to proceed in the next page click in the component + l10n in the next one are you are ready to file it. Select + version current, subcomponent code, type ENHANCEMENT, + Summary GSI file for language., and hit Submit. + The system will ask you if you want to attach a file and what + type. Attach the oo-2.0-km-GSI.sdf file + (or whatever you have called it) + and submit it. You are done.

+

+ +