|
Localization of OpenOffice.org 2.0
This file contains work in progress. The contents of this pages might (and probably will) change often without warning.
Last edited 06/08/2006
The document is aimed at new localizers who have not necessarily had prior contact with OpenOffice.org or with the world of Open Source.
Document Index Planning and preparation
2) Think about your e-mail address 4) Check support for your script 6) Join the localization mailing list 7) Become an OpenOffice.org contributor 8) Announce your intention to undertake the localization project.
Patching (modifying the source to include your language)
10) Include the language in the "Language (locale setting) Dialog Box" 11) Define the default fonts for the language (locale) 14) Prepare an OpenOffice Locale 15) Prepare the patches that will be needed when including the locale file 16) Assure that your script is correctly classified 17) Include your locale in the installation set 18) Configuration options for installation. 19) When your translation is finished, include the language in the build environment 20) Collation (correct alphabetic order for a given locale). 22) Numbering of paragraphs in local script numbers and letters. 23) Outline numbering customization 25) Special case of languages not supported by Windows 26) Localisation in the help system 27) Localisation of other images 28) Special case of languages that use Complex Text Layout scripts
Translation
Localizing OpenOffice.org 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.org 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.org is discussed. OpenOffice.org – 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.org is not a small task, and it has many levels. The lowest one is to assure that OpenOffice.org 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.org is in English or other foreign language. This might be a task that you can do by yourself, but translating the whole OpenOffice.org interface to a new language is a large task, requiring over one man/year, so several people should be involved. Localization of OpenOffice.org involves:
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.
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.org 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.org does not work with your script. In this case you have to try to get such support.
You need to register as a member of OpenOffice.org. 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 register 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.org 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.org related mail.
6) Join the localization mailing list Prior to starting the localization process for OpenOffice.org you should join the OpenOffice localization mailing list. This mailing list is the means of communication with the people in OpenOffice.org 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.org, unless you become involved in other developments outside localization. To join this mailing list, and after logging-in in the OpenOffice.org website, go to: http://l10n.openoffice.org/servlets/ProjectMailingListList scroll down until you see dev@l10n.openoffice.orgNow 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.org 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.org 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.org 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 (yes, this is a pain, but a real signature on paper is the only thing that has legal value, and its purpose is to defend you and any other OpenOffice.org users from possible IP claims from contributors). 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-2Country 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 OpenOffice.org localization team leader according the following rules (taken from RFC 3066):
- 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 you). 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 write 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.
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 will try 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 already have a glossary, then you can 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:
11) Define the default fonts for the language (locale)
For each language, OpenOffice allows us to define what fonts should be use by default for characters in your language. In this section we can define, for example, which font will be used by OOo Writer as default when you use your own language or script, or which font will be used by the user interface for your localized version of OpenOffice 2.0.
Definition of the font default 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: 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.
If your language is not supported by ISO-8859-1, the first font that is listed in UI_SANS will be used by OpenOffice to display the applications' menus.
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.
Warning: the VCL.xcu file is a UTF-8 file, it can be damaged if edited with a non-utf8 enabled editor. Patches should always be in UTF-8.
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.
In case a font used in a document is not available in a computer in which it is opened, OpenOffice has to use another font to represent the text. A large number of these 'fallback fonts' are defined in OOo 2.0, for the most usual latin and CJK fonts. You can nevertheless, add new font substitutions (font fallbacks) for the particular fonts of your script, or change the existing fallback fonts in your own private build. Using fallback fonts is important, as you do not want a font to be automatically replaced with some other font that perhaps has different width, size or other characteristics that turn a document into a mess. Font fallbacks should be defined for at least the fonts defined in the default font lists (see chapter 11) . The font fallback table that establish the relationships between the fonts is defined in the <node oor:name="FontSubstitutions"> of the file: As an example, you can take this node, in which the fallback fonts for the Korean font 'Kodig' are defined
If you want to define your own font fallback nodes, you should include them in this list, and send a patch for them.
Names of fonts in this section must be normalised. All characters must be in lower-case letters and spaces, numbers or other non-letter characters should be eliminated (ignored) in the normalised version of the name. For example, if you have a font called "Kt BT 3", in this node you would have to include its normalised name, which is: "ktbt". When adding a new font like Kodig also the substituted fonts should get a fallback to it. That means that e.g. gulim should fall back to kodig, sungulim should fall back to kodig, etc. This method is clearly unfriendly, as it adds quadratic complexity. Promises to look into it in OOo 3.0 have been made. Another issue that you need to keep in mind is that a font might sometimes have more than one name, such as having an English name and a localized name (some CJK fonts even have three names, in English, Japanese and Chinese). If you use the wrong name, the font might not be found, so a "localized font-name table" is now used to relate the differenet names. In OOo 2.0.0 the ImplLocalizedFontName array in vcl/source/gdi/outdev3.cxx is currently used for this, but in the future OOo plans to provide a mechanism to specify font name translations in VCL.xcu instead.
There are situations when a script is used (e.g. in a document or in the UI) which the selected font does not support. E.g. Times does not support Khmer script. It could happen that Khmer script is used but the Times is active. OOo detects that the font does not cover Khmer and tries to do something reasonable by temporily selecting an alternative font, which supports the script.
The difference between "font fallback" and "glyph fallback" is, that in the "font fallback" case the selected font is not available. In the "glyph fallback" case the font is available, but some of the text rendered in the original font is not supported by the font.
For most localization projects you will not to do anything about glyph fallback, in which case you could just ignore this section. You will only need to include a font for your script in the glyph fallback font list if - after having defined font defaults in VCL.xcu - you are still having problems with the display of your script in the UI or some documents. The current list of glyph fallback fonts is hard-coded in file: but this will probably be changed in subsequent versions of OOo. To add a fallback font for your script in this file you need to look for aGlyphFallbackList[] and add your font to it. Please see that fonts of different types are ordered in lines, with an empty string at the end of each line. Add a line to this list with similar characteristics. The name of the font must be normalised, that it, it must be entirely in lower-case letters and whithout spaces, numbers or other non-letter characters. For example, if you have a font called "Kt BT 3", in here you would have to include its normalised name, that is: "ktbt". Your line in the file would be: "ktbt", "",
14) Prepare an OpenOffice Locale
15) 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: i18npool/source/localedata/localedata.cxxi18npool/source/localedata/data/makefile.mk And for one (and only one) of the following:
16) Assure that your script is correctly classified
All the scripts that have at this point been defined in
Unicode have been classified in OpenOffice as Latin, CTL (indic,
left-to-right) or Asian (Chinese, Japanese Korean). If your script is
CTL or CJK and it has just been added to Unicode, you might want to make
sure that it is listed in the file:
17) Include your locale in the installation set
In order to have installation sets work correctly for your language, modifications are needed in the following files:
You need to add a block of the style:
[OOO_LANGPACK_NAME_1107]
en-US = "Khmer"
de = "Khmer"
[OOO_LANGPACK_DESC_1107]
en-US = "Installs Khmer support in %PRODUCTNAME %PRODUCTVERSION"
de = "Khmer"
Please note that in this case 1107 is the Microsoft locale ID for Khmer in decimal format, you should include the one for your language, which you should have obtained already at this point, but just in case, you can find it in: http://www.microsoft.com/globaldev/reference/lcid-all.mspx
-------------------
You need a line of the type
km 0 1107 # Khmer that includes your ISO language code, the ANSI code-page number for the script, the Microsoft locale ID number (same as in the prior file)... and, if you want, a comment to say which language it is. Warning: ANSI code page number 0 does not seem to work presently, for Unicode languages. If this is the case, please consult issue 47857.
--------------------- In file scp2/source/ooo/file_ooo.scp file you need to make sure that - if your language is a CTL language - the file Common-ctl.xcu is installed, and if it is a CJK language, Common-cjk.xcu and Writer-cjk.xcu get installed. Look for these file names within file_ooo.scp and a a new line for your language. As an example, for Khmer (km) - a CTL language - you should add the line in bold below: File gid_File_Registry_Spool_Oo_Common_Ctl_Xcu
TXT_FILE_BODY;
Styles = (PACKED,MAKE_LANG_SPECIFIC);
Dir = gid_Dir_Share_Registry_Modules_Oo_Office_Common;
Name (th) = "/registry/spool/org/openoffice/Office/Common-ctl.xcu";
Name (hi-IN) = "/registry/spool/org/openoffice/Office/Common-ctl.xcu";
Name (ar) = "/registry/spool/org/openoffice/Office/Common-ctl.xcu";
Name (he) = "/registry/spool/org/openoffice/Office/Common-ctl.xcu";
Name (km) = "/registry/spool/org/openoffice/Office/Common-ctl.xcu";
End
18) Configuration options for installation.
If you would like to change some configuration options, such as having a multi-language installer start by default in a language different from the language used in installation, you should look into this page. This is specially interesting for languages that are not supported by MS Windows and need to build multi-lingual programs, so that English (or other) can be used as an installation language, but then the program is directly installed in your language.
19) When your translation is finished, include the language in the build environment
20) Collation (correct alphabetic order for a given locale).
22) Numbering styles of paragraphs in local script numbers and letters
23) Outline numbering customization
In OpenOffice.org Writer you can number different levels of headings into a structured document. The styles in which these outlies are numbered can be seen in Format-->bullets and Numbering-->Outline tab. In order to change these Outline styles, you need to make the necessary changes in this part of your locale file.
24) Wizards (REVIEW, how to translate the wizards themselves)
Look into the Localization tips page on how to translate them
Some information about these can be found in:
25) Languages not supported by Windows
26) Localisation in the help system
Besides translating the help, it is necessary to actually localise a number of images, as well as some style sheets (which will allow you to use your script in the help, if it is not latin).
The images that need to be replaced by local versions are in You need to create here a folder (with your iso name as folder name) in which you include some localised images. You do not have to localise all of the images. Look into one of the subdirectories (such as km) to see which images have been localised by otherr. then take these images from default_images/res/helpimg/, localise them and create a tar file that contains all the files (path included).
You also need to patch the file that indicates available images. All your files included above must be listed in file: Prepare a patch for this file.
Then you have to look at the contents of where you need to copy the contents of the en-US directory to a directory with your iso name, and then localise the files. Pay special attention to the fonts defined in the css files, as they mark the script that will be used in the help. If the first font in the lists does not contain your script, then the help will not display correctly. Include these files also in the cat file that you created before.
Create an issue to which you attach the tar file with the images and css files. Attach also the patch to helpcontent2/util/helpimg.ilst
27) Localisation of other images
Some other images to be localised are in: Look in one of the language directories to see which images need to be localised. The originals are in ooo_custom_images/industrial/res/commandimagelist/
Create your original versions, and put them in a tar file, including full paths. Sumbit an issue with the tar file.
28) Special case of languages that use Complex Text Layout scripts
The script needs to be included in:
|
