1. Overview

1.1 Translation policy

Management of translations (from 1.5.0+ and 1.4.4+)

All SquirrelMail translations are stored in the locales directory of the SquirrelMail repository. This directroy contains translations of SquirrelMail strings and translations of plugins. Plugin developers can use their own translation packages or rely on translations in the SquirrelMail locales module. If a plugin's translation is not included in the SquirrelMail module, the plugin developer should switch to her/his own gettext domain before using the plugin's own strings.

The HEAD branch of the locales module contains combined strings from SquirrelMail DEVEL and STABLE branches. For example, on 2004-11-23, translations from HEAD can be used with 1.5.1cvs and with 1.4.4cvs.

When SquirrelMail freezes strings in some release, i18n developers will branch HEAD locales to a SM-x_x_x branch and replace the string template with the one that contains strings included only in the selected SquirrelMail version. Strings should be frozen two weeks before planned SquirrelMail release date.

SquirrelMail translations are distributed in packages separate from the main SquirrelMail package. Translation packages should be created within one week after any SquirrelMail release. If translation updates are received after a SquirrelMail release, developers can create other locales packages that include the updated translations.

Only HEAD, latest STABLE and latest DEVEL version branches are actively maintained.

Submitting translations

New and updated SquirrelMail translations can be submitted to the squirrelmail-i18n mailing list.

New translations should be licensed under the GNU GPL or another open license or copyright should be assigned to SquirrelMail developers.

Any translated GNU Gettext Portable Object (PO) file should pass msgfmt -v -c -o /dev/null squirrelmail.po test without any warning or error messages.

A translation is supported only when the number of translated strings exceeds 50% of all strings in squirrelmail.po. A translation can be declared unsupported if it includes translations in other languages. A translation can be treated as supported if the language is similar to American English and only some spelling changes are needed.

Supported translations can be updated by the translation maintainer or member of the translation team. Other people should get approval from the translation maintainer or a member of the translation team. If a translation maintainer does not reply to emails, SquirrelMail developers may assign maintenance of that translation to another person.

An unsupported translation can be updated by anyone who is willing to take over maintenance of that translation.

If a new translation uses a charset unsupported by existing SquirrelMail decoding/encoding functions, there should be a charset mapping to Unicode distributed under an open license or in the public domain.

Developers, Coordinators, Translators

Only SquirrelMail developers have write access to the SquirrelMail repository. They commit all translations created by other people to the repository.

Coordinators maintain translations in some language. If person agrees to be coordinator, it should be indicated in TRANSLATORS file and person's approval is required for all SquirrelMail translations in that language.

Translators maintain only files that they have translated.

I18n developers and coordinators must be subscribed to the i18n mailing list. The translators are not required to subscribe to the list. When a developer commit a translation to the repository, he/she also has to inform the translator and the i18n mailing list.

1.2 Separate translations packages

Since SquirrelMail 1.4.4 and 1.5.0, translations are separated from the main SquirrelMail package. This means that an extra installation step is required if you want to use other languages than American English. By having separate translation packages we can:

• update translations more often that SquirrelMail releases,
• include other plugin translations,
• create combined SquirrelMail and plugins statistics without "download all plugins, find translated ones, rearrange them" scripts, and
• reduce the size of the SquirrelMail core package from 13 MB to 4 MB (or 550 KB packed).

The repository contains a branch for every SquirrelMail verison and a HEAD branch. Only the current STABLE, DEVEL, and the HEAD branches are maintained. Every time a new version of SquirrelMail is released, a separate branch of locales will be created and translation packages for that SquirrelMail version will be released. Translators are strongly encouraged to use SquirrelMail locales HEAD branch for their translations.

1.3 Translation method

SquirrelMail uses gettext based translations. Strings in code use special formating. xgettext program allows extracting the strings from code. msgmerge program combines extracted strings with the ones that are already translated. msgfmt programs compiles gettext strings into binary format. SquirrelMail translations are stored in locale/*/LC_MESSAGES/squirrelmail.po files. Binary translations are stored in locale/*/LC_MESSAGES/squirrelmail.mo files.

SquirrelMail does not depend on gettext support in php. If gettext support is present, SquirrelMail uses it. If there is no php gettext support, SquirrelMail uses own gettext functions. PHP gettext operates with .mo files, SquirrelMail gettext uses .po files.

See gettext manual for more information about gettext.

1.4 Translation tools

To translate the actual strings fill in the msgstr after each msgid with the appropriate translation. There are a few tools which can make this job a bit easier.

http://i18n.kde.org/translation-howto/specialized-programs.html#gui-tools

Gettext

http://www.gnu.org/software/gettext/

KBabel

KBabel is a set of tools for editing and managing PO files created by gettext. Its main component is a powerful and comfortable PO file editor which features full navigation capabilities, full editing functionality, the ability to search for translations in different dictionaries, spell and syntax checking, showing diffs, and much more. It also includes a "Catalog Manager", which is a file manager view that provides an overview of PO files. Last but not least, it includes a standalone dictionary application which provides the additional capability of accessing KBabel's powerful dictionaries.

http://apps.kde.com/na/2/info/id/628

Gtranslator

gtranslator offers a comfortable, colored, and easy way to edit gettext po files and all other flavors of po files (po.gz, mo/gmo) with many comfortable function like find, replace, autoaccomplishment, query capability and personal learn buffer (TM). The GUI also offers you a very nice messages tree to see the translations grouped by status (untranslated, fuzzy) and with customizable colors for the rows.

http://www.gtranslator.org/

PoEdit

poEdit is cross-platform (Win32/Linux/Unix) gettext catalogs (.po files) editor. It is built with the wxWindows toolkit. It aims to provide a convenient way of editing gettext catalogs with features such as fuzzy and untranslated records highlighting, whitespace highlighting, references browser, and header editing, and can also be used to create new catalogs or update existing catalogs from source code by a single click.

http://poedit.sf.net

Emacs po-mode

http://www.emacs.org

1.5 Help translations

The help files should have been written in English using good grammar in the hopes that it would help out people translating. They are divided into functional areas. Each .hlp file represents a different functional block of how the program looks to the user.

Hopefully as SquirrelMail is more widely used, non-English translations will be used to make other non-English translations. You might want to keep this in mind when writing yours. Remember that these will be used all over the world and in many different environments so local language dialects might confuse someone else.

File Structure:

All translated files should be placed under the help directory. Under the help directory create another directory. This directory MUST be named to the two letter standard abbreviation for the language. English is "en" and Polish would be "pl" for example.

The help files are written in a basic xml format. Don't worry, XML isn't hard at all. All it does is contain values inside tags like <start> and </start>. For these help files, the tags must be on their own line like this:

<tag>
Value for this tag
</tag>

There are two types of main tags: <chapter> and <section>. There can be only one <chapter> tag in a .hlp file. However, there can be many <section> tags. Inside both of these tags, their can be any combination of any of the following tags: <title>, <description>, <summary>. Here is an example:

 <chapter>
 <title>
 My first chapter
 </title>
 <summary>
 Just a brief summary
 </summary>
 <description>
 This is a more detailed description that can span many
 lines. Usually, this is the bulk of the help section
 or chapter description.
 </description>

The title can only be one line long. The summary can be many lines, but it should be very short. The description can be very long. It is the main part of the help section.

Translating:

To translate, just copy all the .hlp files from help/en into your new directory that you created for this language (i.e. help/pl). You only need to translate what is in between the tags. Do not translate the actual tags such as <chapter> or <summary>. The tag names need to remain in English. You should only translate the text between tags.

Often there may be other HTML tags such as <b> for bold or <a href...> to make a link. If you see any of these tags, just leave them and don't translate them either. Only translate what is contained inside them if needed.

1.6 Statistics

Statistics for the translations, but the help files, can be found at the SquirrelMail i18n statistics page.