kvirc-data 4:4.2.0-2build1 / usr / share / kvirc / 4.2 / doc / translations.howto.txt

This mini-howto describes the procedure for translating KVIrc in a new language.
-----------------------------------------------------------------------------------

Step 0: Getting the right sources.

First of all you need the SVN version of KVIrc.
To obtain the SVN version you can follow the instructions on
http://www.kvirc.net/?id=svn

The translation stuff is in kvirc/po .


Step 1: Initialize the build environment

Enter the directory containing the KVIrc code and follow the doc/INSTALL*
documentation on how to run CMake to generate the needed Makefiles.



Step 2: Finding out your language code

You must find out the contents of your language code.
Usually this is a string formed of at least two letters and it
can be found by examining the contents of your $LANG shell variable
or by looking at http://translation.sourceforge.net/HTML/teams.html
Examples of such codes are "it", "en", "hu" or "pt_BR"



Step 3: Generating the list of messages to translate

You must perform this step only if it is the first time that KVIrc is translated
into your language. If you're going to update an existing translation then
you can jump directly to step 4.

Enter your build directory and run this command to extract the messages from the
sources:

# make messages-extract

A series of .pot files will be created in the subdirs of build_directory/po/
Each file refers to a specific component of KVIrc: eg. the main translation file
is located in build_directory/po/core/kvirc/kvirc.pot
Create a copy for each of these files named kvirc_xxx.po where xxx is your
language code found in step 2.

# cd po/core/kvirc
# cp kvirc.pot kvirc_xxx.po
# cd ../kvs
# cp kvs.pot kvs_xxx.po
# cd ../../modules/about
# cp about.pot about_xxx.po
# cd ../modules/addon
# cp addon.pot addon_xxx.po

and so on for all the other modules; you are not forced to translate all the
files at once, but creating the files skeleton for all components is recommended.



Step 4: Translating the messages

If you just followed step 3 then you have just created the *_xxx.po (eg.
kvirc_it.po) files where xxx stands for your language code (found in step 2).
If you jumped directly here from 2 then you need to find the existing
*_xxx.po files in the kvirc/po subdirectories.
If no such files exist for your locale, you probably missed to create them in
step 3. 

You can translate *.po files using a simple text editor (that _have_ to support
the UTF-8 encoding), but it's strongly advised that you use a translation software
such as lokalize for linux/kde or poedit for windows.

Note on the format of the translation files:
The *.po files contains a set of strings like the following one:

#: /path/to/the/file/which/contains/the/string: line number
msgid "The original english message"
msgstr "The translation goes here"

The msgid is the original message that needs to be translated
and msgstr is the translation (that will be initially empty, when
the kvirc_xxx.po file is created).

The msgid can contain html tags, escapes like "\n" and format strings
like "%s". You MUST match the tags, escapes and format specs in the msgstr
strings. Keep special attention to the format specifications (%s, %W,
%Q...)..
They must remain EXACTLY the same order as in the msgid: exchanging the
order or writing a wrong format spec will lead to crashes sooner or later.



Step 5: Adding the translation to the install system

Once you have translated some strings you can try to run the translation in
KVIrc. If you are updating an existing translation then you can jump
directly to step 6.

You need to force the build system to pick up your newly created translation
files and compile it. This is again an one time step. You'll just need to
clean your CMakeCache.txt (located in your build directory) and re-run CMake
again for it to pick up the new translation file, then build KVIrc as usual.
When it has finished building, move to the next step.



Step 6: Trying the translation

Run make and wait until it finishes.
Ensure the $LANG environment variable is set to the correct locale, and run
KVIrc

# export LANG="xxx"
# kvirc

KVirc should then pick up your translation file and use it.



Step 7: Updating the translation when the sources change

In the process of KVIrc development, new message strings gets added inside the
source files, while some others can change or even get removed.
When you do a svn update to obtain the latest sources you should then enter your
build directory and run:

# make messages-update

This procedure will update your *_xxx.po files with the new messages and mark the
old messages as either fuzzy or invalid.
The invalid entries must be re-translated completely again while the fuzzy entries
have minor changes and can be probably adjusted in few seconds.



Misc notes:


If you're in doubt about some translation, you could take a look at how
similar sentences have been translated in the KDE *.po files, or in other
softwares. If you need some further help, contact us on our mailing list or on
irc (irc://irc.freenode.net/#KVIrc).

Since many of the modules have their own translation files then
the procedure above may be repeated for the po/modules/*/ subdirectories.
Anyway you are not forced to translate all the files at once: a partial
translation will work anyway.

When you're satisfied with your translation you may send your *.po files to the
KVIrc mailing list asking for inclusion in the SVN. If you want to maintain the
translation in the future then you may also apply for a SVN account.


Happy translating :)
Szymon Stefanek