LibreOffice Localization Guide

From The Document Foundation Wiki
Jump to: navigation, search

This document is aimed at new localizers who have not necessarily had prior contact with LibreOffice or with the world of Open Source in general. It is based on Localization of OpenOffice.org 2.0 tutorial by Javier Solá.

Planning and Preparation

What you need to know

Localizing LibreOffice does not require highly specialized knowledge of programming or of the Open Source world. It does not require knowledge of a specific operating system, such as Linux, either. You can localize LibreOffice on Microsoft Windows if you want to. Once you have done it, your localized resources can be very easily used to localize LibreOffice 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 are also strongly advised to subscribe to at least one mailing list in which localization of LibreOffice is discussed.

LibreOffice – 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.

Check out the list of LibreOffice language teams 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 in it. Bear in mind though that sadly, not all teams have taken time to list themselves in that page, so a missing table row doesn't necessarily mean that there is no team. You are also advised to check out other pages in Category:L10n and take a quick look at Pootle, and if the status of your locale is still unclear, probably contact the L10n mailing list.

Localizing LibreOffice is not a small task, and it has many levels. The lowest one is to assure that LibreOffice handles your script (if it is not Latin-based) correctly. LibreOffice should allow people in your country to work using your script, even if its interface is in English or other foreign language. Checking for support for your script might be a task that you can do by yourself, but translating whole LibreOffice interface to a new language is task much larger, requiring over one man/year, so ideally, several people should be involved.

Localization of LibreOffice involves:

  • Assuring that LibreOffice can work with your script in the platform in which you want to use it.
  • Assuring that the program recognizes your language as one of the languages it can work in (this may involve some changes in the source code, but don't get scared – it's likely that you won't have to make them yourself).
  • Translation to your language. Translation has different levels:
    • First and foremost – translating the menus and messages of the program itself (around 28.000 strings / 93.000 words for all LibreOffice applications combined).
    • Second – translating help files of LibreOffice, not a small task (another 45.000 strings / 440.000 words).
    • The third level adds the development of documentation for LibreOffice in your language. If you still have resources after all this, you can complete the work by developing LibreOffice 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…

Think about your e-mail address

If you start the localization process, you will have to subscribe to at least one mailing list, and your e-mail address will end up running around, and probably receiving a lot of spam. You should probably consider the quality of your e-mail provider's spam filters and if they aren't adequate, think about using an e-mail address that is different from your personal mail address for the whole localization process (and not only for LibreOffice).  

Install LibreOffice

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 LibreOffice 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 will find it in the download page.

Also, later on, if you find and file issues for the LibreOffice project, and want to know if and when corrections are integrated, you might also want to download and install the latest available builds. You will find them in the Pre-releases page.

The installation files will take up about 200MB of disk space, and you will need about 500MB more to actually install LibreOffice (and probably even more during the installation).  

Check support for your script

It might be that LibreOffice does not work with your script. In this case you have to try to get such support. See tough things to do if your script is not supported yet for details and contact the developer mailing list for further advice.

Register with LibreOffice

In process, you will need to register with the various services that LibreOffice uses. We don't use single sign-on (yet?), so this will mean separate accounts for separate services. For example, to subscribe to LibO mailing lists, you will have to send empty messages to list+subscribe email addresses; to file bugs and provide patches, you will need to register with Bugzilla; to translate online, you'll need to create an account in Pootle, and so on…

Join the localization mailing list

Prior to starting localization of LibreOffice, you should join the LibreOffice localization mailing list. This mailing list is the means of communication with the people in LibreOffice that drive the localization, 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 LibreOffice, unless you become involved in other developments outside localization.

To join this mailing list, just send an empty message to l10n+subscribe@global.libreoffice.org. This will make the LibreOffice mailing 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 and will be able to send mails to the list yourself.  

Announce your intention to undertake the localization project

The first step is to let people at LibreOffice know that you are going to start the localization project, but before you do this, please check if there is already a project for your language listed in the Language Teams page. This list might not be ordered alphabetically, make sure to check it well.

There are several possibilities:

  • 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.
  • 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 probably can take the project over.
  • Your language is not in the list. In this case check out if the locale exists and has any recent activity in the appropriate project (LibreOffice x.x.x – UI) in Pootle.
    • If it is active, it's quite likely that the team leader simply forgot to list his team. In this case, contact the mailing list to find out who the leader is and make sure to remind him or her to add missing information to the Language Teams table.
    • If it is inactive and lacks a lot of strings, the project is likely in a dormant state. In this case, act as if the language is in the FIXME list: write to the list and ask if anybody has information about this project. If there are no answers, you probably can take the project over.
    • If the language is not listed in Pootle at all, it's a pretty good indication that you will have to start from scratch. In this case, prepare for a lot of translation work (or better, find yourself a few comrades) and contact the localization mailing list telling your intentions and listing all the necessary information (see below).

The necessary information that you need to gather to be listed in the Language Teams 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 these links: Language codes - iso639-2 Country codes - iso3166-1
  • You should also mention if the language is only spoken in a country or is shared by several countries/regions, and if there are sufficient difference in the way the language is spoken and written in the different countries/regions as to require separate treatment. Based on this data, an internal ISO-CODE for your localization will be assigned by the LibreOffice localization team leader according the following rules (taken from RFC 3066):
    1. Use ISO 639-1 if possible. This happens when the language is spoken in a single country (or there are no major differences between how it is spoken in different countries), or when the ISO code of the language is the same than the ISO code of the country (es, fr).
    2. Use ISO 639-2 (three letter language code) if no ISO 639-1 (two letter) code exists.
    3. Use ISO 3166 country code if necessary, to specify versions of languages with the same language code in different countries, such as Spanish in Chile (es-CL), Portuguese in Brazil (pt-BR), or English in the United States (en-US).
  • The name of the language in English.
  • The Microsoft locale ID, in decimal and hexadecimal formats. You can find this numbers in [1].
    If your language does not appear in the list, then say so in the LibreOffice Localization mailing list and the language will be assigned a LibreOffice 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 yourself).

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.  

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 LibreOffice in order for it to work in your language and script, using your local conventions in numbers, and the preferred fonts for your script.

These steps are not very complicated, and we will try to explain them to you very clearly, but they might take some time. Some of them require time from other people at LibreOffice, 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 with 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 LibreOffice 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

Source code modifications

Include the language in "Language Settings" Dialog Box

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

The Language Settings dialog

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.

There are two levels of language/locale support:

Add the new language

For the mere support of UI localization and to have the language/locale available in character attribution and thus for spell-checking (if there is a spell check dictionary avialable that is) it is sufficient to add it to a few places in the source code, for details please see adding a new language or locale that also explains how to have this done for you.

After you file the request to add a new language, it is a good idea to send an e-mail to the localization 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 bug xxxxx. This will make people who are in charge of localization aware of the fact that the process for your language has started and that you need some help from them.

Submit locale data

To support a locale to the degree that it is listed in Locale setting and available as default document language its locale data is needed, for details please see how to submit new locale data.

Advanced source code modifications

Some languages may require further work, please see advanced source code modifications.