SquirrelMail - Webmail for Nuts!

When saving, enter the following:

           ______ ZZZZ ZZZ  _   _ ZZZZZZZZ 
          |  ____| ZZ   Z  | | | |Z  ZZ  Z 
 ##  ##   | |__    ZZ   Z  | | | |   ZZ    
 ### ##   |  __|   ZZ   Z  | | | |   ZZ    
 ######   | |____   ZZ Z   \ \_/ /   ZZ    
 ## ###   |______|  ZZ Z    \___/    ZZ    
 ##  ##              ZZ             ZZZZ   
 ##  ##

Visit Preferences to set your user name

== Translating !SquirrelMail ==

'''Just Starting'''

You must have gettext installed. If it is not installed you can download the sources from <ftp://ftp.gnu.org/pub/gnu/gettext/>.

Find the language code for the language you are going to translate into. A list of language codes can be found at <http://lcweb.loc.gov/standards/iso639-2/langhome.html>.

If there is a 2 letter code for the language, use this.

You may also need country code, which can be found at <http://www.iso.org/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html>.

'''Getting the template'''

Create a directory squirrelmail/locale/''language_code''/LC_MESSAGES/. Copy squirrelmail/po/squirrelmail.po into this directory. This is the file that is going to be translated.

'''Doing the actual translation'''

To translate the actual strings fill in the msgstr after each msgid with the appropiate translation. There are a few tools which can make this job a bit easier at <http://i18n.kde.org/translation-howto/specialized-programs.html#gui-tools>.

Win32 users may found poEdit (http://poedit.sf.net) useful.

Convert the translated {{squirrelmail.po}} into a binary file by running the command {{msgfmt -o squirrelmail.mo squirrelmail.po}} in the directory where the translated {{squirrelmail.po}} is residing. Add the {{-c}} option to the {{msgfmt}} command if you want to be sure that your translation is correct. Restart your web server to make sure your translation gets loaded.

Add the language name and language code to the array at the top of {{squirrelmail/functions/i18n.php}}. (Not true since 1.4.4 and 1.5.1.)

'''Submission'''

We'd love to get your translation so we can include it in the distribution! Contact he internationalization team at the [http://squirrelmail.org/docs/admin/admin-12.html#mailinglists internationalization mailing list].

'''Miscellaneous'''

There is also a small script in the {{po/}} directory that can help in creating charset mappings from the mappings files that are provided by the Unicode consortium.

'''Strange strings'''
Some strings in !SquirrelMail translation does not look English.

: ''msgid "Ma&#121;"''
:: Short form of May month. In English full name of month is the same as its short form. &#121; is the HTML code for the letter "y".

: ''msgid "D, F j, Y g:i a"''
: ''msgid "D, F j, Y G:i"''
: ''msgid "g:i a"''
: ''msgid "G:i"''
: ''msgid "D, g:i a"''
: ''msgid "D, G:i"''
: ''msgid "M j, Y"''
:: These are PHP codes of various [http://www.php.net/manual/en/function.date.php date/time formats].

: ''msgid "sec_remove_eng.png"''
:: This is name of image in images directory that says "This image has been removed for security reasons". If you want to use English version - don't translate it.

: ''msgid "A"''
:: !SquirrelMail marks answered emails with this string in message listing.

: ''msgid "AUTHOR Said"''
: ''msgid "Quote Who XML"''
: ''msgid "On DATE, AUTHOR Said"''
:: These are names of reply citation styles visible to end user. See Options -> Personal Info -> Default Reply Citation Style:

'''Updating a translation'''
The text strings in the program changes over time. This means that some strings that are already translated are no longer used, and that new strings are added. It is therfore neccessary to maintain the translations.

The template {{squirrelmail/po/squirrelmail.pot}} should always be updated, thus containing all strings in !SquirrelMail. To merge all new strings in this file into an existing translation run these commands:

<code>
cd squirrelmail/locale/''your_language''/LC_MESSAGES
msgmerge squirrelmail.po ../../../po/squirrelmail.pot > squirrelmail.po.new
</code>

This should keep all strings that are unchanged and comment out all strings that are no longer in use. You might want to make a copy before doing this. Continue with '''Doing the actual translations''' above.

!SquirrelMail has a {{mergepo}} script that can be used to update translation file.

== Translating the help files ==

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:

<code>
<tag>
  Value for this tag
</tag>
</code>

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:

<code>
<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>
</chapter>
</code>

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 inbetween 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.

'''Submission'''

== Translating plugins ==

This is an older section; most pertinent info should be contained in previous page in this tutorial.

!SquirrelMail's plugin translation responsibility falls, for now, onto plugin developer's shoulders. The "official" way to translate a plugin is to create a plugin domain and activate it each time the plugin's strings are outputted. And of course swithing back to the !SquirrelMail domain when finished. For those that are not familiar with gettext please have a look at Paginator plugin. This is a very simple plugin (already discontinued as it has been integrated into !SquirrelMail core) that shows how this can be done.

'''Example of how to do it'''

This is a simple example of how the translation was done in the View as HTML plugin:

<code>
/* i18n.php defines the _() syntax */
include_once('../functions/i18n.php');
/* Now tell gettext where the locale directory for your plugin is
 * this is in relation to the src/ directory
 */
bindtextdomain('view_as_html', SM_PATH . 'plugins/view_as_html/locale');
/* Switch to your plugin domain so your messages get translated */  
textdomain('view_as_html');
if($show_html_default == 1) {
    echo "<a href=\"$new_link&amp;view_as_html=0\">";
    echo _("View as plain text");
    echo "</a>\n";
}
else {
    echo "<a href=\"$new_link&amp;view_as_html=1\">";
    echo _("View as HTML");
    echo "</a>\n";
}
/* Switch back to the SquirrelMail domain */
bindtextdomain('squirrelmail', SM_PATH . 'locale');
textdomain('squirrelmail');
</code>

'''Creating the locale files'''

To create a .po file to add translations too, you need to run xgettext:
:{{xgettext --keyword=_ -d <plugin_name> -s -C *.php}}

Better yet is to actually try to parse PHP files (not C files):

: {{```xgettext --keyword=_ -d <plugin_name> -s -L php *.php```}}
:: or
: {{```xgettext --keyword=_ -d <plugin_name> -s --language=php *.php```}}

* The {{--keyword}} option tells xgettext what your strings are enclosed in.
* The {{-d}} is the domain of your plugin which should be the plugin's name.
* The {{-s}} tells xgettext to sort the results and remove duplicate strings.
* The {{-C}} means you are translating a file with C/C++ type syntax (ie. PHP).
* The {{-L}} means you are translating a file with PHP type syntax.
* The {{--language}} means you are translating a file with PHP type syntax>
* The {{*.php}} is all the files you want translations for.
Once run, the command should give you a file called {{<plugin name>.po}} that will look something like this:

<code>
# SOME DESCRIPTIVE TITLE.
# Copyright (C) YEAR Free Software Foundation, Inc.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: PACKAGE VERSION\n"
"POT-Creation-Date: 2002-06-18 11:22-0600\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=CHARSET\n"
"Content-Transfer-Encoding: ENCODING\n"

#: setup.php:77
msgid "View as HTML"
msgstr ""
</code>

There will be a msgid for each string you need translated.  The msgstr is the translation of msgid.  You need to copy this .po file for each translation you do.  The .po files will go into directories for each language laid out as follows.

<code>
<plugin_name>/
  locale/
    <country_code>/ (ie. no_NO, fr_FR, cs_CZ, etc)
      LC_MESSAGES/
        <plugin_name>.po
</code>

In each of the directories you need to run the {{msgfmt}} command to create the .mo file that is used for the translation:
:{{msgfmt -o <plugin_name>.mo <plugin_name>.po}}
The .po file can be called anything, but the .mo file needs to be the same as the gettext domain which should be the plugin name.

Before executing {{msgfmt}} you should to set charset to the appropiate charset code. You can find what code to use looking into {{squirrelmail-1.2.x/locale/xx_XX/LC_MESSAGES/squirrelmail.po}} file.

'''Example'''

If you have a translation file like the example above, you could change it to:

#: setup.php:77
msgid "This is the text to be translated"
msgstr "This is the translation"
</code>

Save this as {{<plugin_name>.po}} in your {{<plugin_name>/locale/fr_FR/LC_MESSAGES}} directory.  Change to that directory and run {{msgfmt -o <plugin_name>.mo <plugin_name>.po}}  Now change your !SquirrelMail settings to French and what used to say {{"This is the text to be translated"}} should now say {{"This is the translation"}}.  If that works, then start translating for real.

'''Updating the locale files'''

If you want to update an already existing PO file, use the msgmerge command to merge the existing old PO file and a new created PO file.

Here you will also find some notes about Gettext utilization: TranslateGettext

Status of currently available translations: http://l10n-stats.squirrelmail.org

== Submission ==

Summary of change:
Add document to category:

Editing HelpTranslating