Localization of OpenOffice 2.0

 

This file contains work in progress.

It is only published for public review leading to its improvement, change... or utter destruction, if necessary.

At this time the localization process for OpenOffice 2.0 has not yet been fully defined, and this work is therefore incomplete.

This documenthas not yet been checked nor approved by OpenOffice.org localization specialists, so it might also contain errors.

Any advice is welcome, be it on form, language, structure or contents.

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

 

 

Javier SOLA - www.khmeros.info - Last edited 11/23/2004

 

The document is aimed at new localizers who have not necessarily had prior contact with OpenOffice.org or with the world of Open Source. Its translation part will also be aimed at localization projects that need to upgrade from the 1.1.x branch to 2.0

 

On how to localize the help, please look at this PDF document written by Frank Peters, you might also want to look into this specification document.

 


 

Document Index

 

1) What you need to know

2) Think about your e-mail address

3) Install OpenOffice

4) Check support for your script

5) Register in OpenOffice

6) Join the localization mailing list

7) Become an OpenOffice.org contributor

8) Announce your intention to undertake the localization project.

9) Plan your work

10) Include the language in the "Language (locale setting) Dialog Box"

11) Include the automatic font substitution table for the language (locale)

12) Prepare an OpenOffice Locale

13) Prepare the patches that will be needed when including the locale file

14) Assure that your script is correctly classified

15) Translation

 

 


 

 

1) What you need to know

Localizing OpenOffice does not require highly specialized knowledge of programming or of the Open Source world. It does not require either knowledge of a specific operating system, such as Linux. You can localize OpenOffice on MS Windows if you want to. Once you have done it, your localized resources can be very easily used to localize OpenOffice in other platforms (if your language script is supported by those platform, or less easily if this basic support is missing).

You do need to understand how to download programs and data from the Internet, how to install them and how to run them (following detailed instructions). You also need to subscribe to at least one mailing list in which localization of OpenOffice is discussed.

OpenOffice – as the world of Open Source in general - is a collaborative effort. There is no reason whatsoever for which somebody should do anything that you need or want, including fixing bugs, adding new features or accepting patches. You need to be polite, patient, and – if you really want something – charming and convincing… or learn how to do it yourself. There are a lot of people in the mailing lists that will be happy to help you if you ask in the right way.






The table of languages presently supported and ongoing localization projects is in: 





http://l10n.openoffice.org/languages.html

Check it to make sure that there is not already a localization project for your language. If there is one, write to the person that appears as project contact, to know the status of the project and see if it is makes sense to participate on it.

Localizing OpenOffice is not a small task, and it has many levels. The lowest one is to assure that OpenOffice works correctly in your script (if it is not the Latin script), as it allows people in your country to work using your script, even if the interface of OpenOffice is in English or other foreign language. This you can do by yourself, but ranslating the whole OpenOffice interface to a new language is a large task, requiring over one man/year, so several people should be involved.

Localization of OpenOffice involves:

  • Assuring that OpenOffice can work with your script in the platform in which you want to use it.

  • If they are not already there, assuring that some changes are made in the OpenOffice source, so that the program recognizes your language as one of the languages it can work in.

  • Translation to your language. Translation has different levels. The first one is translating the menus and messages of the program itself (around 22.000 messages altogether for all applications in OpenOffice), the second one includes also the translation of the help pages of OpenOffice, not a small task. The third level adds the development of documentation for OpenOffice in your language. If you still have resources after all this, you can complete the work by developing OpenOffice training materials in your own language.

But, before we go into details about all this, there are a few things that you might want to do in order to be prepared to face a localization project...


2) Think about your e-mail address

If you start a localization process, you will have to subscribe to a number of mailing lists, and your e-mail address will end up running around, and probably receiving a lot of spam. We recommend that you consider using for the whole localization process (and not only for OpenOffice) an e-mail address that is different from your personal mail address.


3) Install OpenOffice

You have to become familiar with the programs that you are going to localize. If you are not a regular user, we recommend that you change to OpenOffice and use it in your everyday work.

We recommend that you install the version that you are going to localize (probably the last stable release). You can find it in:

http://download.openoffice.org/index.html

Also, later on, if you find and file issues for the OpenOffice project, and want to follow if and know when corrections are integrated, you might also want to download and install the latest available build: Check for it at:

http://download.openoffice.org/680/index.html

Each one of these programs will be between 60 and 80 Megabytes in size.


4) Check support for your script

It might be that OpenOffice does not work with your script. In this case you have to try to get such support.

  • On Linux, OpenOffice is supported by version 2.6 of IBM's ICU (International components for Unicode) library. ICU does accept code supporting new languages. You should write such code thinking that it has to work with the current version, as well as with version 2.6. The you need to add your changes to OOo's current patch for ICU, at:

http://external.openoffice.org/source/browse/external/icu/icu-2.6.patch

This patch file MUST NOT be created manually.

There is a dmake target that does this from the sources available under ${INPATH/misc/build/icu/ after the module was built once, and files were modified: dmake create_patch

You have to create the patch on a Unix or Linux platform, using Windows will create the wrong patch.

  • On MS Windows, OpenOffice receives script support for CTL languages from Microsoft's Uniscribe engine, contained in the file usp10.dll. If you want to try to get support for your language in such engine, you should get in touch with Microsoft (don't tell them that it is for OpenOffice, though).

  • On Mac... I don't know (please help here!!! ***REVIEW***).


5) Register in OpenOffice

You need to register as a member of OpenOffice. This will allow you to subscribe to mailing lists, submit issues and information that you want included in the program (patches that are needed for your language), etc…

To subscribe just go to www.openoffice.org and click in Register, on the top left corner of the screen.

In the next screen you will be asked to provide a login (your name, initials, or anything you want) and the e-mail account in which to want to receive all the mail coming form OpenOffice. Once you enter this data and hit register, an e-mail will be sent to your e-mail account with your password. With the username that you have provided and the password, you can now login in the main page of the website.

Once you are logged in, you can select the MY PROFILE entry in the menu at the left of the page. There you can change your password to one you can remember better or you can change the e-mail address to which you receive e-mail related to OpenOffice.

What OpenOffice actually does is to create an e-mail account YourLogin@OpenOffice.org that is redirected to the e-mail address in which you want to receive OpenOffice related mail.


 

 

6) Join the localization mailing list

Prior to starting the localization process for OpenOffice, you should join the OpenOffice localization mailing list. This mailing list is the means of communication with the people in OpenOffice that does certain parts of the localization process, as well as with other localizers that might help you figure out specific parts of the localization adventure. It will become your main window into the world of OpenOffice, unless you become involved in other developments outside localization.

To join this mailing list, and after logging-in in the OpenOffice website, go to:

http://l10n.openoffice.org/servlets/ProjectMailingListList

scroll down until you see

dev@l10n.openoffice.org

Now you have to decide if you want to receive the e-mails from this list one-by-one (when they are sent) or all of the messages sent each day together in a single message (digest format). When you are starting in the process, your interaction with the list might be high, so message-by-message can be a good option when you start, you can always change it to digest mode later.

Click on Subscribe. This will make the OpenOffice automatic list manager send an e-mail to your account asking you to confirm your intention of subscribing to the list. Reply to that message following the instructions (which usually are “just hit reply and send, don’t do anything else”).

If you have done everything correctly, you will receive a “Welcome to the list” message… and you are on. From this moment on you will receive all mails sent to the list.

 


 

7) Become an OpenOffice.org contributor

There is one more step that you have to take: becoming an OpenOffice contributor. Being a contributor allows you to send data to OpenOffice.org (it actually allows OpenOffice.org to receive data from you without fearing you will ask anything in exchange or claim that some part of OpenOffice belongs to you and nobody else, or to a third party).

To become a contributor you actually need fill and sign the form that you will find at

http://www.openoffice.org/licenses/jca.pdf

and fax it to the number indicated in the form and then mail it by postal mail to the address that the form mentions.

If you need more information on why you need to do this, follow the link to:

http://www.openoffice.org/FAQs/faq-licensing.html#usinglicenses

Sending the fax and then the letter will put you in the contributors list in:

http://www.openoffice.org/copyright/copyrightapproved.html

And you are ready to start…

 


 

 

8) Announce your intention to undertake the localization project.

The first step is to let people at OpenOffice.org know that you are going to start the localization project, but before you do this, do check a few things.

-           See if there is already a project for your language in:






 http://l10n.openoffice.org/languages.html

(the order in this list is not alphabetical, check the whole list)

There are several possibilities:

o Your language is already listed, including all the data and a contact of a project manager. In this case you should contact directly that project manager and try to figure out what is happening, status, etc… It does not make sense to have more than one project for exactly the same language, but maybe the project that is being carried on is different from the one you want to do (for example, there is Khmer for Cambodia, but you want to do Khmer for Khmer-speaking minorities in Vietnam, which is sufficiently different to justify the localization work, and you are prepared to do it). If the project is sufficiently similar, you should consider joining the existing project.

o The language is listed, but it is either in the FIXME list or it does not include a project contact name. In this case you should write to the list and ask if anybody has information about this project. If there are no answers, you should declare your project as if it was not in the list.

o Your language is not in the list. Send the necessary information to be added to the list.

The necessary information that you need to gather to be listed in this page (that is, for your project to be considered as an on-going localization project) is:

- The ISO codes for your language and country (or region). If you don’t know them, follow this links:

Language codes - iso639-2 
Country codes - iso3166-1

     You should also mention if the language is only spoken in a country or it is shared by several countries, and if there are sufficient difference in the way the language is spoken and written in the different countries as to require separate treatment. Based on this data, an internal ISO-CODE for your localization will be assigned by the Open Office localization team leader. If the language is spoken in single country (or there are no mayor differences on how it is spoken in different countries), it will probably only include your language code, if it is spoken and/or written quite differently in more than one country, it will include the language code and the country code, separated by a hyphen (the usual convention is to write the language code in small letters and the country code in capital letters), so that the localization of the same language in a another country can be assigned a different code with that country's iso code. Some examples:

km - Khmer spoken in Cambodia mainly, but also Vietnam and Thailand, but without major differences.

es-ES - Spanish in Spain

es-CL - Spanish in Chile

-           The name of the language in English.

-           The Microsoft locale ID, in decimal and hexadecimal formats. You can find this numbers in:

http://www.microsoft.com/globaldev/reference/lcid-all.mspx

If your language does not appear in the list, then say so in the OpenOffice Localization mailing list and the language will assign an OpenOffice internal number. This number is used for the cases in which information is stored or read in Microsoft file formats.

-           Inform about the script of your language. Does the language use Latin script? Does it have its own script? If so, what family does the script belong to, specifying if it is Indic, if it uses use pictograms, if it is written from right -to-left, etc... and any other information that might be relevant, including character sets that can be used to render (show) it.

-           Give a contact e-mail address for the manager of your localization project (probably yours).

Note: You might see that most languages in the language table have a language number. This is because localizations prior to version 2.0 had to be assigned an internal language number, but it is no longer the case.

If you want to start a new project, you should put all the above information in an e-mail to the localization list, indicating your intention to start a localization project, and stating what is the status of the project. The person in charge of the list of localization projects will add your language and data to it, including the current status for your project. At the moment, the person in charge of handling them is localization project co-owner Pavel Janík, but you should not rely on specific names given in this documentation, as they might change.

 


 

9) Plan your work

And now you are ready to start your localization project. Next we will go one-by-one, through all the changes that need to be done to OpenOffice in order to work in your language and script, using your local conventions in numbers, and the preferred fonts for your script.

These steps are not specially complicated, and we have tried to explain them to you very clearly, but they might take sometime. Some of them require time from other people at OpenOffice who will not always be available, and who probably already have a long list of tasks they have to get to before they can help you on your localization. You should start the actions, and do your part of the work, and then wait until the right people have the time to integrate them in the source.

You should also start looking at the translation part of the project. Translating OpenOffice requires gathering or developing a wide range of computer, mathematical and accounting terms in your own language, a glossary. If you do not have such a glossary, you should start working on it as soon as possible, because it will probably take at least two or three months to gather all the information.

If you have already a glossary, then you could start already on the translation of the messages, in parallel to the technical work

 


 

 

10) Include the language in the "Language (locale setting) Dialog Box"

Check the latest build to see if your language appears in the language dialog boxes. To do this go to Toolsà Options, and there click on Language Setting, and in there in Languages.

 

 

 

Search for the name of your language in the Locale Setting dialog box. If it is not there, you have to request having it included.

To request it, you should file an issue requesting it. To do this, login into the OpenOffice website, then click on 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 Inclusion of language xxxx in the Locale Setting dialog box, in the text box politely request the inclusion of your language in the locale setting dialog box… and hit Submit. The system will ask you if you want to attach a file and what type, skip this… and finished.

 

After you file the issue, it is a good idea to send an e-mail to the dev@l10n.openoffice.org mailing list (yes, the one you are already subscribed to) saying that you are starting localization to your language and that you have requested inclusion in the Locale Setting dialog box in issue xxxxx. This will make people who are in charge of localization aware of the fact that the process for your language has started and tell them.

Technically, the process requires:

  • Approval of the name for your language by the project linguist (in both English and German)

  • Preparing patches for the following files. Before preparing the patches, you should make sure that you language is NOT in those files (for the version that you want to localize, look into How to prepare a patch for more information). Some of these patches might not be necessary in Ooo2.0. Details on the patches will be added when the localization process is finished. (***REVIEW, Should this document point at preparing patches, instead of writing to the list?)

  • tools/inc/lang.hxx

http://util.openoffice.org/source/browse/util/tools/inc/lang.hxx

  • tools/source/intntl/isolang.cxx

http://util.openoffice.org/source/browse/util/tools/source/intntl/isolang.cxx

  • svx/source/dialog/langtab.src

http://graphics.openoffice.org/source/browse/graphics/svx/source/dialog/langtab.src


 

 

11) Include the automatic font substitution table for the language (locale)

 

The font substitution system of OpenOffice defines automatic substitution fonts for each language. When somebody types a character (in the word processor, for example), and the character is not included in the currently selected font, OpenOffice looks for another font that has this character. You can define what fonts (and in which order) OpenOffice will attempt to use when looking for a font that is fit for your language.

 

Definition of the font substitution table for your language requires the modification of the file VCL.xcu. If you have OpenOffice installed in your computer, this file is in:






 





<OOoDir>/share/registry/data/org/openoffice





 

(where <OOoDir> is the directory in which OpenOffice is installed)

You can find the latest versions of this file in

http://util.openoffice.org/source/browse/util/officecfg/registry/data/org/openoffice/VCL.xcu

The file is divided into blocks (called nodes), one for each language. The first line of the node for a language includes the standard ISO code for the language.

There are two different cases you have to consider here.

1) If your language uses Latin characters (ISO-8859-1) and you are happy with the default fonts for English. You need to have two lines added to this file:






+ <node oor:name="YourLanguageCode" oor:op="replace">





+ </node>





 





For Swahili, for example, these lines will be:





 





+ <node oor:name="sw" oor:op="replace">





+ </node>





 

2) You language uses a different script. Find in the file a language that is somehow similar to yours (at least in the same group, either Latin, or Asian (Chinese, Japanese, Korean) or CTL (Complex text layout, including Indian and some Southeast Asian languages). For example, for Khmer we have taken Thai as the model.

Copy the node for that language (that is, the block of lines that refers to that language, from <node to </node>), change the language code of the new node to the code of your own language. Then, in each one of the sections, change the font list to a set of fonts that support your language (fonts to which OpenOffice will change if it finds a character from your languages).

A node looks like this:

<node oor:name="km" oor:op="replace">

<prop oor:name="UI_SANS" oor:op="replace" oor:type="xs:string">

<value>Khmer OS System;Khmer OS;UniKhm</value>

</prop>

<prop oor:name="CTL_DISPLAY" oor:op="replace" oor:type="xs:string">

<value>Khmer OS System;Khmer OS;UniKhm</value>

</prop>

<prop oor:name="CTL_HEADING" oor:op="replace" oor:type="xs:string">

<value>Khmer OS System;Khmer OS;UniKhm</value>

</prop>

<prop oor:name="CTL_PRESENTATION" oor:op="replace" oor:type="xs:string">

<value>Khmer OS System;Khmer OS;UniKhm</value>

</prop>

<prop oor:name="CTL_SPREADSHEET" oor:op="replace" oor:type="xs:string">

<value>Khmer OS System;Khmer OS;UniKhm</value>

</prop>

<prop oor:name="CTL_TEXT" oor:op="replace" oor:type="xs:string">

<value>Khmer OS System;Khmer OS;UniKhm</value>

</prop>

</node>

You can see that fonts are separated by the ‘;’ character. You have to use the internal name of the font, the one that appears on your font menu when you select fonts in OpenOffice or any other program (not the name of the file that contains the font). This names might have spaces, this is not a problem, include them. Spaces are significant, so do not put spaces before or after the ‘;’ signs, nor at the beginning or the end of the font list.

You might select different substitution fonts for different application, each one of prop statements refers to different tools or situations.

Don’t forget that this file will be used in several platforms and by people who might have different fonts installed. Include in your list fonts for these platforms; if you know them (Macintosh typically has different fonts). Try to assure that any user will at least have one of the fonts that you have included in the list.

When you have finished with this file, and made sure that this is what you really want, you have to create an issue for the Localization (L10n) project, and submit a patch for file officecfg/registry/data/org/openoffice/VCL.xcu. 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 PATCH, Summary Patch for VCL.xcu for language…., and hit Submit. The system will ask you if you want to attach a file and what type. Attach the patch that you have been working on and… submit it. You are done.


12) Prepare an OpenOffice Locale

 

Please look in How to prepare an OpenOffice Locale

 


 

13) Prepare the patches that will be needed when including the locale file

 

When including the locale file in OpenOffice, it is also necessary to include information about this locale in a couple of files. You should prepare the necessary patches for files (***REVIEW***, this information will be completed when it is clear if these or other files will be included in OOo 2.0):

 






i18npool/source/localedata/localedata.cxx





i18npool/source/localedata/data/localedata_others.map





i18npool/source/localedata/data/makefile.mk

which you can find in the web in:

http://l10n.openoffice.org/source/browse/l10n/i18npool/source/localedata/


14) Assure that your script is correctly classified

It is not clear if this will be necessary for 2.0 (***REVIEW***), but, just in case, it is mentioned. If a language is CTL or CJK, it needs to be marked in this file.


http://util.openoffice.org/source/browse/util/svtools/source/config/languageoptions.cxx



15) Translation

The OpenOffice software itself (messages)

PO format files that include all the messages that need to be translated in OpenOffice 2.0 (around 22.000 messages) are available.

The PO (portable objects) format is a standard format used in translatable files. Specific editors that handle these files facilitate the translation process, and they are often hooked to "translation memory" systems (databases that keep all the messages that have been translated), facilitating also the upgrade process from one version to the next.

The translation process described here consists on the translation of the PO files, running checks on them for possible mistakes, correction of these mistakes, and finally conversion of the PO files to a format that is easily acceptable for OpenOffice. The process is technically very simple.

For details, please look into the Complete Translation Process page

Help

PO files that include the information in the HELP files are also available (around 32.000 messages). (***REVIEW***)

On how to localize the help, please look at this PDF document written by Frank Peters, you might also want to look into this specification document.

Documentation

(***REVIEW***, Search for sources and information)

Training materials

(***REVIEW***, Search for sources and information)