# The &lokalize; Handbook

Nick
Shaforostoff

    shaforostoff@kde.ru

2007-2009
Nick Shaforostoff
&FDLNotice;
2008-09-10
0.3

&lokalize; is a computer-aided translation system that focuses on productivity and quality assurance. &lokalize; applies a paragraph-by-paragraph translation approach when translating documentation, and takes a message-by-message approach when translating &GUI; components.

&lokalize;
localization
translation

## Introduction

When you start &lokalize; without any command-line arguments, you will see two big multi-line edits as well as a bunch of toolviews. These views can be stacked (similar to tabs), shown separately, or hidden. Translation files consist of many English-target pairs called messages. A message typically correspond to a single string in the user interface, or one paragraph in the documentation. The purpose of the first multi-line edit is to display the original part of the pair. The purpose of the second multi-line edit is to display the translation. You can navigate through the messages via the Catalog Tree view or by using Page Down and Page Up.

It is recommended that you get used to the keyboard shortcuts instead of the menus and toolbars for increased productivity. For example, use the &Alt;_ to switch between views when they are stacked into tabs, or &Alt;Q to initiate a query when in the WebQueries.

A message may be translated or untranslated. A translated message translation may be approved or non-approved (also called fuzzy sometimes). If the message is non-approved, its translation is rendered in italics. &lokalize; allows you to easily navigate through the file according to the state of their translation. See Go menu for the shortcuts. When navigating, untranslated messages are treated as non-approved.

## Projects

The projects are one of the main concepts in &lokalize;. A project is represented by a file that contains paths, folders with translations, templates, and other files: glossary file, automation scripts, translation memories. Whenever &lokalize; opens a file without a project loaded, it will search for a project file in the parent folders (up to four levels). Alternatively, you can specify the project file via the `--project` flag when starting &lokalize; from the command line.

Translation memories (unlike project files, glossary and scripts) are not shared between the translation team members, as they are created and stored under the user's home folder, meaning that the translation memories for all of the projects are stored in the same folder and thus can be used when other projects are opened.

### Project Overview

The Project Overview tab displays a file tree with statistics for a current project, such as the percentage of translated messages completed and the last translator. It allows you to open a selected file in new tab of the current &lokalize;, window.

## Glossary

Have you ever become tired of typing the same long text sequence several times just because it would take more time to find its translation for a copy and paste? Now you will only have to find the (frequent) word sequence in the Glossary View, and then insert it by pressing a shortcut.

Of course the glossary should be populated with word sequences first. &lokalize; has a handy glossary editor that allows an explicit search over the entire glossary.

Glossary view in the bottom right corner displays glossary entries appropriate for the current entry
Glossary view in the bottom right corner displays glossary entries appropriate for the current entry

## Translation Memory

The Translation Memory view allows you to drag and drop a folder with translation files from say Dolphin into the view, and then, within few minutes, translation suggestions will be shown automatically on the message entry switch. To insert the translation suggestions into the file, use &Ctrl;1, &Ctrl;2 and so on, depending on the number of suggestion.

Pressing F7 will open Translation Memory tab, which allows free querying TM. Clicking a search result will open corresponding file on corresponding entry. If you want to quickly open some file in the project (and it is added to TM), then instead of browsing Project Overview you just type its name into File mask field accompanied by '*'.

TM engine indexes all entries, including fuzzy and untranslated ones. This allows it to completely replace Search-in-Files feature which required scanning every file in the project each time a search is done.

&lokalize; with translation memory search results for the current entry
&lokalize; with translation memory search results for the current entry

## Translation Synchronization Capabilities

The Sync Mode (previously known as Merge Mode) saves a great deal of time for the editors, and for cases when two or more translators are working simultaneously on the same file, or when one has to maintain translations for several branches of software.

&lokalize; allows quick navigation through the messages that differ, and displays word-by-word differences. Also, &lokalize; has two Sync views - Primary Sync and Secondary Sync. They are identical, but the former is usually used to merge translations and second to keep in sync translations for two software branches.

After you copied translation from auxiliary file (synchronized it), any subsequent changes made to this entry will be replicated back to auxiliary file.

### Merging

One use of Sync Mode is reviewing changes made by (new) contributors, when you cannot be sure of the quality of the work done.

Open a base file, then drop its changed version into the Primary Sync view, followed by &Alt;Down or &Alt; Up (remember that shortcuts may be modified in a usual way for all &kde; apps) to navigate through entries that are different.

&lokalize; used for merging changes in translation
&lokalize; used for merging changes in translation

### Replication

Sync Mode may also be used to make changes to translation for two branches simultaneously. Set Branch Dir path in your project options to the path that corresponds to base dir of the branch, and Secondary Sync view will automatically open files from branch. Then, each time you make changes in files of your main branch, they will automatically be replicated to the branch (of course, if it contains the same english string).

For example, if you work on KDE translation, you can checkout trunk to `/home/xx/hacking/kde/trunk/l10n-kde4/YOUR_LANG` and branch to `/home/xx/hacking/kde/branches/stable/l10n-kde4/YOUR_LANG`. Create &lokalize; project: `/home/xx/hacking/kde/trunk/l10n-kde4/YOUR_LANG/project.ktp` and set `BranchDir=../../../branches/stable/l10n-kde4/YOUR_LANG`, then work via this project, and commit changes in both trunk and branch dirs.

### Original Diff

When original text changes, gettext tools update translation files and mark entries with changed original text as fuzzy (or non-approved in other terminology). They store previous original text so that translators could see what changes exactly were made. &lokalize; simplifies life of translator and highlights parts of original text that were changed in Original Diff view.

&lokalize; highlighting parts of original text that were changed since translation was last reviewed
&lokalize; highlighting parts of original text that were changed since translation was last reviewed

## Credits and License

&lokalize;

Program Copyright © 2007-2009, Nick Shaforostoff shaforostoff@kde.ru

Some code was taken from &kbabel;, the &lokalize; predecessor.

Documentation Copyright © 2007-2009 Nick Shaforostoff shaforostoff@kde.ru

Author:

- Nick Shaforostoff shaforostoff AT kde.ru

See the &lokalize; homepage for more details.

&underFDL; &underGPL;

&documentation.index;