## Translating

### Translating desktop entry

On Linux systems .desktop files are used to build system menus that lists applications available to users. Fontmatrix ships with such a file as well. It is located in root directory with source code and gets installed to /usr/share/applications or /usr/local/share/applications, depending on your preferences.

To get localized menu entry you need to do a very simple thing:

1. Open this file in your preferred text editor and make sure you opened it as a UTF-8 encoded text file.
2. Create a new entry which looks like "Comment[LANG]=A font manager", where LANG is a two-letter code for your language (as referenced by ISO-639-1) and everything after "=" is translated.
3. Create a new entry which looks like "GenericName[LANG]=A font manager".
4. Save.
5. Test by running 'sudo make install' (if Fontmatrix is already installed or just 'sudo cp fontmatrix.desktop /usr/share/applications/' and look in the menu.

Send the updated file to us.

### Translating user interface

The very first thing you need to translate Fontmatrix into your native language is to get source code from the current developpement branch. To do this, you need a Git client (git being the regular command line client). Then type

`git clone https://github.com/fontmatrix/fontmatrix.git`

somewhere in your home directory to fetch source code, so that you always have access to it.

Then you will need to install Qt development package that contains Linguist — the application to assist you with translating. On Linux start your package manager and look for a package named something like qt4-dev, install it.

The next steps are as follows:

1. Go to the top level directory of source code.
2. Create the build directory eg: mkdir build and cd into it.
3. Run Cmake command with whatever options you want plus -DTRANSLATOR:string=LOCALE, where LOCALE is a two-letter code for your language (as referenced by ISO-639-1), lowercase, e.g. fr for French or de for German. If necessary, you can specify a country code and thus form a string like fr_FR
4. Run "make translation" to create a new translation file in fontmatrix/src/messages/ directory.
5. Open your fontmatrix-LOCALE.ts file in Linguist and start translating.
6. To test your translation, run make install in the build directory. This will create a binary file called fontmatrix-LOCALE.qm (and Fontmatrix itself if you did not run this command before) and install it in the right place. If the LOCALE for which you translate is not the one which is set for your system, run LC_ALL=LOCALE fontmatrix to tell Fontmatrix to load that specific LOCALE.
7. When your work is done, compress this fontmatrix-LOCALE.ts file to a ZIP, GZ or BZ2 archive and submit it via patches and patches tracker or tell us about it on IRC and we will help you to sort this out.

Here are some tips to help you make translation better.

Translating Fontmatrix takes a while, so it's best to translate those parts of user interface that you use most of the time. This will give you a false, but useful feeling of accomplishment and motivation to finish the whole work.

Test your translation as frequently as possible. This is especially important for dialogs that you rarely use.

Make sure you find a good balance between short and easy to understand phrases and words. English language is known to have relatively shorter words, so in most cases your translation will make user interface a bit larger. But if you start using abbreviations or shorter synonyms that don't quite fit the context, users won't appreciate that either.

A lot of translatable messages use variables like %1. Those are substituted by some values. For example, in "Block (%1):" (Glyphs tab) this variable is substituted with percentage of a chosen Unicode block's coverage, e.g.: "Block (74%):". When you type these variables manually, you can make a mistake and the trick with a variable won't work. So it's better to paste original text to translation entry field by pressing Ctrl+B in Linguist and then replace this original text with translation, leaving all present variables intact.

A good part of translatable messages are names of Unicode blocks and OpenType features. Even though these technologies are meant to serve wide world community with all its complex languages and scripts, it is typical to have little to no information on them in a language other than English. This is 21st century to you. So please refer to good solid dictionaries for correct names of languages that are used for most Unicode blocks, to Unicode specification for the rest of the blocks and to OpenType specification for names of OpenType features that you see in the Sample text tab.

### Translating documentation

The documentation is inside help directory and consists of menu.xml file that defines table of contents, HTML files with text and illustrations in PNG or JPEG files.

Every translation is kept in its own directory named with two-letter language code like ru for Russian or es for Spanish. So download source code, unpack it and start with creating this directory.

Now copy contents of en directory to your language directory. Before you start translating, open help/LANGUAGE/CMakeLists.txt file in your preferred editor and replace all instances of "_EN" with "_LANGUAGE", where LANGUAGE is a two-letter code for your language as well, uppercase. Then open help/CMakeLists.txt and add another line that looks like this:

ADD_SUBDIRECTORY(${FM_HELP_DIR}LANGUAGE)

where LANGUAGE is a two-letter code for your language, lowercase this time.

These two files are used by the build system to find out what files to install.

Start translating. It's best to translate table of contents first and proceed with actual content later. To translate table of contents open menu.xml file in your editor of choice and translate values of every text attribute. E.g. for <area text="Setting up" file="setting_up.html"> translatable text will be "Setting up".

To test your translation open a terminal window, go to the top level directory with source code, rebuild and reinstall Fontmatrix. After you rebuild it for the first time, you will only need to run 'sudo make install' to update files.

If user interface is not localized, you might want to do it before translating documentation. Some users might complain and tell you that user interface in English is a de-facto standard and thus localized documentation should refer only to English UI. But this is just because they have grown up to use unlocalized software, so don't worry, let them play silly buggers and move on.

Some illustrations actually display other applications like FontForge which may be not localized for your language. In that case just use already available screenshots from English version of the documentation.

The English (and Russian) translations have screenshots with Dust theme for both GTK+ and Metacity (and GTK+ engine for Qt), and Droid Sans 9pt font. You don't have to try to reproduce that, but please be visually consistent across your translation.

Please keep all of your illustrations below 800 pixels on the longer side.

When you are done, archive help/LANGUAGE directory with your translation and send it to us.