~amsn-daily/amsn/amsn-packaging

LANG-HOWTO

Version 2.2

File name: msn/lang/LANG-HOWTO

This document and its contents are licenced under the 

GNU-FDL licence version 1.2 or up.

http://www.gnu.org/copyleft/fdl.html

If you modify this file, please update the version and add 

your name to the credits at the end.

This little document is a guide to translator and translation

managers that works or wants to work in aMSN. It is indeed a

little document, but has a lot of information. We suggest you 

to print it and leave it within the reach of your hands if you

are serious in this translation business.

Another word of warning: if you are in doubt, please ask! 

We will be pleased to help you. The right place to ask 

questions is our discussion list: amsn-lang@lists.sourceforge.net

You must subscribe to post there. Instructions on how to subscribe

can be found here: http://lists.sourceforge.net/lists/listinfo/amsn-lang

One of our goals is to be the most internationalized 

free software / open source project of the world. 

And to achieve that we need you!

Thanks for the interest on the aMSN project!

Index:

*. Introduction.

   What is this aMSN translation stuff all about?

0. The most important thing

   Explains why and how to subscribe to the amsn-lang forum.

1. For translators

   For those who want to translate aMSN for their own language, 

   or help improve/extend the existing translation. Must read.

	-- Rules that must be followed

	-- How to add a new language

2. For translation managers

   For those who are in charge of coordination of local or global 

   translation efforts and commiting the langfiles to the CVS server.

   If you want to start a local translation effort please read this.

3. For both - useful tools

   Some of the tools you *must* use before sending your files. These

   tools are included with aMSN. 

============

Introduction

============

There are many ways you can help the aMSN project. One of them is 

by translating the software to other languages. This can be easily

done. Another way is proofreading the current translations in search

of typos and errors and missing (untranslated) messages. There is

plenty of work for everyone who wants to be involved, and this seems

to be your case as you are reading this file ;-)

The aMSN Messenger can be translated into any language you want. 

It is easy to do so because all of the translated messages for every 

new language are stored in a special file called langfile. The name 

of each and every langfile indicates clearly the language it contains. 

The format is langXX, where XX is the two-caracter ISO code of your 

language. For instance, for the italian language, whose ISO code is IT, 

the langfile is called langit. A few examples:

English: langen

Spanish: langes

German: langde

French: langfr

The ISO codes for the english, spanish, german and french languages are, 

respectively, en, es, de and fr. Later in this document we will see how

to determine the country code for new languages. For the languages already

present in aMSN (some completely translated, some not) please refer to our 

translation effort page: 

http://amsn.sourceforge.net/modules.php?name=Translation

You can help us enormously by checking periodicaly the webpage above

and, if your language has any missing key (a key is one of the many 

messages shown on the various aMSN windows, menus ans dialog boxes), 

translate it and send us the file. Even if your language has zero 

missing keys, it is important to scan the file for possible errors 

or bad writting styles introduced by other translators.

This document (msn/lang/LANG-HOWTO) deals ONLY with the langXX files

(that is, the language files that translates aMSN's messages, menus 

and dialog boxes). Please read the present document completely, make sure 

you understand everything and ask what to do 

(at amsn-lang@lists.sourceforge.net) when in doubt.

There are other files that need translation and proofreading, like the

HELP, FAQ and README files. There is another document called DOCS-HOWTO,

located at msn/docs/DOCS-HOWTO. *PLEASE READ THAT DOCUMENT TOO*

Tip: this LANG-HOWTO file surely contains many errors. If you are a

native english speaker, please help us by proofreading it.

===========================

0. The most important thing

===========================

You MUST subscribe to the amsn-lang@lists.sourceforge.net mailing

list. There you can discuss various issues with the members of the

translation team, including:

- The best way to translate a word or phrase;

- What character code you should use or not use;

- Best translation practices;

- Issues and questions about this HOWTO;

- Coordination of local efforts;

- Stablishment of local language translation managers.

One important thing you MUST ask at the amsn-lang list is if there

is somebody already doing what you intend to. 

For instance, if you want to translate the langfile file into greek

(langel) you shoud ask first. This way, if there is another person

already translating the same langel you won't waste your time.

You can subscribe to the list by visiting this page:

   http://lists.sourceforge.net/lists/listinfo/amsn-lang

Remember, joining or not is not an option. You MUST subscribe.

==================

1. For Translators

==================

When you add new keys, you should send the entire updated langXX

file, compressed using GZIP or ZIP (.gz or .zip files),

to the translator managers, who can be reached at

    amsn-translations@lists.sourceforge.net

Diff files are also accepted, and can be used in certain cases where

you update more than one file with a single diff or you merge

different files into one, but the best and easyest way (for both

translators and managers) is to send the whole translated file. If

in doubt, send the entire compressed file.

Keys sent in the body of the email will be ignored, due to character

coding and line break issues.

If you are sending a new file, or you have changed the encoding of the

translated file, don't forget to tell us!

You can help us by translating some sentences to your language,

or modifying wrongly translated sentences (proofreading).

RULES THAT MUST BE FOLLOWED:

----------------------------

1. Download the latest langfile you want to work on from the website

or via SVN. You will find the link at the translation page:

http://www.amsn-project.net/translations.php

-NEVER use files from a stable AMSN package, as they are probably out

of date, and you'll find yourself translating many keys that are

already translated in the latest language file version.

When in doubt, ask! (amsn-lang@lists.sourceforge.net)

2. Add the missing keywords from the list at the bottom of the page

to the language file.

-Alternatively, you can also download "langen" file (the master file),

and use the script "missing.py" in the lang/ folder to check what are

the missing keys. When in doubt, ask! (amsn-lang@lists.sourceforge.net)

3. Translate the english sentences.

-BE CAREFUL with $1, $2... parameters that appear in some

sentences. You can change their position, but they must appear on

the sentence, they 'll be substituted during execution with some

values.

-Every key must be in a single line. There should be no line breaks.

The key name (first word on the line), and the translation must be

separated by a single blank. Don't use Tabs.

-Keep the current encoding unless you have a good reason to change it.

You can probably find the the file encoding using the unix 'file' command,

or just by checking the 'langlist' file in the amsn folder. Use

a text editor that supports that encoding. If for some reason, you

change the encoding (for example, you decide to go for utf-8 instead of

iso8859-1 for spanish), please DON'T FORGET to tell us the new encoding

when sending your updated translation.

When in doubt, ask! (amsn-lang@lists.sourceforge.net)

4. Check the translated file with one of the scripts provided 

in the lang/ folder. For example:

 $ ./missing.py langXX

It will tell you if there are any errors or missing keys to translate.

You'll need the "langen" file in the same folder in order to check the

missing keys. It can be downloaded from the translations web page too.

-It's not necessary that the keys in the file are sorted, but it is

better to have them sorted, in order to find keys more easily. You can

sort them automatically using the "sortlang" script in the lang/ folder.

Please MAKE SURE there are no errors in the file before sorting, or the

file can be messed up.

When in doubt, ask! (amsn-lang@lists.sourceforge.net)

5. When all errors are fixed, compress (gzip or zip) the updated file

and send it to amsn-translations@lists.sourceforge.net

-We will ONLY accept gzipped or zipped langfiles.

-We will NOT accept, in ANY way,

individual keys received in the body of the email. You MUST send

the COMPLETE langfile (for instance, langit if you are italian)

ATTACHED to de email message. Only in special cases we will accept

diff files or incumplete translation files with a few keys.

-As stated above, keys sent in the body of the email will be

IGNORED and DISCARDED.

-If you changed the file encoding, please TELL US THE NEW encoding you used,

in order to change it in the langlist file.

-Langfiles sent to other email addresses than

amsn-translations@lists.sourceforge.net will also be IGNORED and

DISCARDED. When in doubt, ask!

If not possible, or you're just translation a few keys, you can just

send (although it is not the ideal) a text file attached to the

mail, in the form:

keyname1 translation1

keyname2 translation2

that is, the keyname, followed by ONE BLANK SPACE (no tabs or

similar), and followed by the translated string, no need to include

the original english string, or similar. One key per line, no extra

blank lines in the middle. Including the keys directly in the email

text is a bad idea, as mail clients usually split long lines and

change the character encodings, which leads to mistakes.

OTHER KINDS OF CONTRIBUTION WILL BE REJECTED, IN ORDER TO MAKE THE

JOB EASIER TO THE MANAGER.

I hope you understand, there's usually one person in charge of

updating the translations, and there are more than 50 languages, so

there are many translations and submission. Don't make it more

difficult :)

When in doubt, ask! (amsn-lang@lists.sourceforge.net)

HOW TO ADD A NEW LANGUAGE

-------------------------

1. Choose a short identifier for your language (for example english

- en). It is better that you use the correct ISO code for your

language. ISO codes for languages can be found at

    http://www.w3.org/WAI/ER/IG/ert/iso639.htm

Always use the 2-letter code for your language if it exists (for

instance, fr for french, pt for portuguese). If your language has

only a 3-letter code (for instance, ale for aleut, pap for

papiamento) you must use it, though. 

When in doubt, ask! (amsn-lang@lists.sourceforge.net)

For languages spoken on colonial lands, you shoud use the language

ISO code followed by an underline and the country ISO code in CAPS

(fr_CA for canadian french, pt_BR for brazilian portuguese). 

Language ISO codes:

    http://www.w3.org/WAI/ER/IG/ert/iso639.htm

Country ISO codes:

    http://www.bcpl.net/~jspath/isocodes.html

Some codes have been mistakenly taken (for example, langbr once was 

taken for the brazilian portuguese, but the correct code would be

pt_BR, br alone refers to the breton language). If you find that

the ISO code for your language has been taken by mistake for

another language, scream your lungs out at the amsn-lang list and

we will fix things up ;-)

When in doubt, ask! (amsn-lang@lists.sourceforge.net)

2. Download the english language (langen) file from

http://www.amsn-project.net/translations.php

3. Rename the file to langXX, where XX the ISO language code you've

chosen. Remember that, for some languages, the ISO code has three

(3) letters.

4. Translate the whole file, except for the first word of each line

(that is the key). Do not use <TAB> characters in the translated

files, only spaces are allowed. Tabs break aMSN. Make sure you choose

a good encoding for your language, and you use a good editor that

supports that encoding. A good choice is to use UTF-8, an unicode

encoding that supports all languages.

5. Add the language to the 'langlist' file in the amsn folder

(it's an XML file). Make sure you set the correct encoding in

'langlist', the same that you used when writing the file. Put

your langXX translation file in lang/ folder in AMSN.

6. TEST THE FILE. Use the new file in your local aMSN before

sending. Go through every menu and every dialog box. Assure that

all messages have the proper size. If you don't know how to do it,

ask for help on the amsn-lang list. Also use the scripts provided in 

the lang/ folder to check for errors in the translation. There is a 

description of these scripts in section 3 of this document.

When in doubt, ask! (amsn-lang@lists.sourceforge.net)

7. Only after testing for one or two days, send the new file,

compressed with gzip or zip, to:

    amsn-translations@lists.sourceforge.net

Send to this email only! Submissions to other emails will be ignored

and discarded. Don't forget to tell us the language name (official "english"

name, and "local" name), and the encoding you have used. It can be

hard for the translation managerthe translation managerss to guess

the encoding!

8. When in doubt, ask! (amsn-lang@lists.sourceforge.net)

===========================

2. For Translation Managers

===========================

When a new translation arrives to you, you should only accept it if

is a diff file or a complete compressed langXX file.

Do not accept other kinds

of submissions, 'cause our users have the sad habit of sending sparse

translated keys by mail, and it's a big job :)

*TEST THE FILE WITH THE missing.py SCRIPT!*

*YOU, AS A TRANSLATION MANAGER, ***MUST*** DO THIS TO ENSURE THE FILE IS OK!*

Do this before commiting the file and only commit it if it's ok!

If the file has any problems, the best thing to do is to return it to 

the translator and ask him to correct it. If you really need to edit a 

file (for whatever reason) be sure you use a multilanguage editor and 

also use the correct encoding for each language --- or you can corrupt it.

Encodings are in langlist file (msn/langlist). This file is XML-formatted 

so it must be easy to understand.

If you reject a translation by any reason, do it politely. 

Explain the reasons of why you're rejecting it and always: 

'Thanks anyway' ;)

What should I do if...

-...I receive two lang files of the same language? Reject one, the

oldest, or the less complete.

When you get big contributions (not just 1 or 2 keys), or when you

notice a person is very active (sending frequent translation

updates for a language), you should add him to the CREDITS file. 

You should tell him/her about this, and ask him/her if he or she

wants to be removed (nobody wanted to be removed until now, but

it's polite to ask :))

When adding a new language, make sure to create an entry in the langlist file found in the top amsn directory. See the existing entries for the format.

==========================

3. For both - Useful tools

==========================

In the lang/ folder you have some useful scripts. 

Remember to replace XX in langXX for the two-letter

code of your language. Example: Valenciano = langva.

The tools are:

- missing.py: will list the missing keys in the langXX file, that

is, the keys that exist in langen (the master language), but not in

langXX. It will also warn about errors and count the number of 

untranslated keys. It's a very useful script, please use it!

Usage in Linux:

./missing.py langXX

Usage in Windows (must have the Python interpreter installed):

python missing.py langXX

- sortlang: will sort the language file. BE CAREFUL. Don't apply

sortlang if there are spplited translations, as sorting it will

sort these spplited lines, and it will be quite difficult to join

them again. So please fix any spplited lines before sorting.

Sorting is not mandatory, but it's recommended to sort before

commiting to the CVS.

Usage in Linux:

./sortlang langXX

To use it in Windows you must have Cygwin installed.

The syntax is identical. http://www.cygwin.com

- convert.tcl: converts the given source, in the source encoding, 

to the given destination file using the given encoding.

Usage in Linux:

./convert.tcl source_file 

source_encoding dest_file dest_encoding

Usage in Windows:

wish convert.tcl source_file source_encoding dest_file dest_encoding

If you are in Linux using bash, remember that the auto completion is your friend...

=========

 CREDITS 

=========

File created by Alberto Diaz

Version		Created		Author					Obs

  1.0		06.Jan.2004	Alberto Diaz				Initial file

  2.0		03.May.2004	Henrique Cesar Ulbrich (Hatredman)	Total rewrite

  2.1		Unknown		Alvaro Iradier				Inclusion of new tools (section 3)

  2.2		29.Aug.2004	Henrique Cesar Ulbrich (Hatredman)	Instructions for FAQ, README and HELP files

Please be don't mess with the versioning system. It's quite simple to determine

what version your mods should take. If you just add a few items or correct some,

ad one to the MINOR version number (example, 1.1 to 1.2). If you totally rewrite the file (or rewrite

large portions of it) add one to the MAJOR number and make the minor zero (example: 2.6 to 3.0).

These credits are not a reward or reconition for you, but a way

to hunt for a guilty person if something goes wrong he he he...

We have the CVS versioning anyway.