Dolda Webmail Localization Guide Introduction Dolda Webmail now has native language support in that it can translate visible HTML strings into a language chosen by the user. It does this by keeping a table of the English strings as used by the PHP code and their translated counterparts. There is one table per language. The tables are maintained in human-readable text files which are then converted into PHP code (still human-readable, but not very legible) by a Perl script. There are a number of additional Perl scripts to help with the maintenance of these files. These are described in detail in the following sections. New translations would be very appreciated, and the purpose of this document is to describe how to translate the strings in Dolda Webmail. Related Files The files that are related to localization process of Dolda Webmail are the following: * include/initlang * include/appendnew * include/finduntrans * include/makelanginc * include/*.langdesc * include/lang-*.inc The initlang, appendnew, finduntrans and makelanginc files are Perl scripts to help with the maintenance of the string tables. They will be described in detail in the following sections. The files named *.langdesc are the human readable string tables. The file format is very simple. There is one line that describes an English message as used by the PHP code, immediately followed by a line that contains the translated version of this message, followed by an arbitrary number of blank lines before the next English line, for legibility. Long lines can be broken into several by ending each line in a backslash (\). Omitting the translation line indicates that the corresponding English message has not yet been translated. The lang-*.inc files are the PHP include files that are actually read and used by Dolda Webmail when it runs. They are automatically generated from the *.langdesc files. The * in the *.langdesc and lang-*.inc files represents the HTML language code for that language. For example, `en' for English, `se' for Swedish, `de' for German, `ja' for Japanese, etc. Beginning a new translation To begin translating Dolda Webmail into a new language, use the initlang script. It will search all the PHP files that Dolda Webmail consists of for translatable strings and create a langdesc file without any actual translations on stdout. Its usage is very simple - for example, to create a langdesc file for Korean, run the following command from the `include' directory: ./initlang >ko.langdesc That will create the file ko.langdesc, ready to begin translation on. To make Dolda Webmail use the new langdesc file, you need to compile it into a corresponding include file (see the next section), and then add the language to the lang.inc file. Adding the language to the lang.inc file incorporates two steps: 1. Add a line that maps the language code to a human-legible language name. See close to the end of lang.inc for the languages that are already implemented and write a new line according to that pattern. For example, to make Dolda Webmail support Korean, add this line: $languages["ko"] = "Korean"; 2. Include the PHP language file. Again, see the end of lang.inc for how this is done for the already implemented languages. For example, to add Korean, add a line like this: include('lang-ko.inc'); Translating To do the actual translation, open the langdesc file you have created, or an existing langdesc file, in a text editor of your choice. As straightforward as this step may seem, there is one very important detail that must be pointed out; the langdesc files _must_ be saved using the UTF-8 character encoding scheme. How do to that depends on the text editor, of course. In GNU emacs, type C-x RET f utf-8 RET; you should then see `-u:--' in the modeline, where the `u' indicates that UTF-8 is being used. In the GNOME text editor, gedit, select UTF-8 as the character encoding in the `Open File' dialog box. You may have to use the `Add or Remove...' option to add UTF-8 to the selection menu if your system has not already added it by default. Some systems, such as RedHat release 8 or higher, already use UTF-8 by default; on these systems, no extra steps should be necessary, since text editors on these systems should be using UTF-8 by default. Once you have opened the file, locate a message you wish to translate, and simply write the translation on the empty line below (suggestedly leaving an empty line below your translation for the sake of legibility). The following things should be noted: * If you must use quotation marks (") or dollar signs ($), escape them with a backslash (for example, `usage of \"quotation\" marks'). This is because the strings are directly copied into PHP code, and PHP treats unescaped quotation marks and dollar signs specially. * If the string to translate contains percent references, such as `%s', it indicates that the string is passed through the PHP sprintf function, and that percent reference is replaced by another string, such as the string `At %s, %s wrote:', which is placed at the beginning of the new message when replying to mails, where the the first %s is replaced with the date of receipt of the mail that is being replied to, and the second %s is replaced with the sender of the mail that is being replied to. Due to grammatic constructions, you may need to reorder these percent references; for example, in Swedish, one translation would require the first %s to be replaced with the sender address and the second to be replaced with the date. To accomplish this, write `%n\$s', where the n should be replaced by the place number in which the percent reference you wish to insert appears in the English message. For example, the above mentioned Swedish translation would become `%2\$s skrev, %1\$s:'. There are also a few special messages, that are not really English messages. Most of these are simply message that would be too long to be in the source code, but there is also the langnotice message. The langnotice message is where you are supposed to write a reference to yourself as the translator or maintainer of the language. The string should be something like this, if it were English: Translated into English by Fredrik Tolf, fredrik@dolda2000.com The other ones are, as of this writing, `sslwarning', `htmlwarning' and `exturlswarning'. These are long since they are supposed to warn the user of potential security problems that they ought to be aware of, and also explain why it is an issue. They are also, for that reason, some of the most important messages to be translated. See the en.langdesc file for the original English text of these messages. When you are done translating, the `makelanginc' Perl script is used to convert the langdesc file into the PHP-readable include file. Its usage is very simple - just run it with the language code as its sole argument in the `include' directory. For example, to convert the ko.langdesc file into the lang-ko.inc file, run this command: ./makelanginc ko Alternatively, if you have GNU make installed on your system, you can simply run `make' in the `include' directory to rebuild all the include files that need to be rebuilt. This only works once the include file already exists, though, so you need to run the above command at least once if you are starting on a new language. The `finduntrans' script prints out a list of untranslated strings for reference if you give it a langdesc file on its stdin. For example, to find all untranslated strings in ko.langdesc, run this command: ./finduntrans