Multilanguage support

Surgeweb now has extensive multilanguage support throughout the interface (as of surgemail version 4.2g-22+) to customise the interface for both for English and non English languages. Most of the strings displayed in the surgeweb interface can now be translated or customised (with a few exceptions for now, as noted later on).

Surgeweb language translation features are similar to the language translation capabilities of the other surgemail web interfaces, but are notably different in a few areas.

Implementation is string table based, which puts all languages - English and others - on an equal footing. This means actual english phrases can be modified without it "breaking" the translations for all other languages. Also it makes it easy to find the strings to translate.
Customisation is hierarchical, and allows changes without modifying the base implementation. This is much like all the customisation concepts in the rest of surgeweb.
Distinct support for UK / US English.
Languages selection is displayed in native text rather than English. eg. Français instead of French
There are sample "partial translations" (some shown below) of 26 non English languages to allow you to get an idea what the surgeweb interface is capable of and would look like with a full translation. A full translation requires approx 800 phrases to be translated, although you can just translate a subset if you wish. The sample translations have only 16 phrases translated.

How multilanguage support works

The surgeweb template files contain placeholder strings along the lines of $$st_cmd_reply$$ which are string table lookup entries that get replaced with the actual textual representation before getting served to the web browser. So in the case of the Reply button, this would be replaced with "Reply" in English or with the string "Antworten" if German was selected.

Reply button as defined in the template files:

  <input type=button value="$$st_cmd_reply$$">

Sample lang*.dat file format:

# note1: Any line staring with a # is a comment
# note2: lang*.dat files need to be UTF8 encoded

# Language definition of the way languages get displayed in the interface
#  - both the english name and the native display name
#  - type of translation:   *=full translation,
#                         o/+=partial sample translation (under dropdown/more...)
#                           -=hide interface
# Here English is a full translation and german and spanish demo translations
lang:*:English:English (UK)
lang:o:German:Deutsch
lang:+:Spanish:Español

# -----------------
lang:English
# -----------------

# Strings to add to English, individual strings can be added to alternate languages
st_username         Username
st_password         Password
st_cmd_reply        Reply
    German:         Antworten
st_cmd_forward      Forward

# Generally alternate languages are listed as complete standalone tables,
# possibly in their own files. "lang:" must match a full lang line at top of file.
# -----------------
lang:Spanish
# -----------------
st_username         Nombre de usuario
st_password         Contraseña
st_cmd_reply        Responder
st_cmd_forward      Reenviar

These surgeweb string tables are defined using the sum total of lang*.dat files in the surgemail/surgeweb/tpl and the surgemail/surgeweb/custom directories. Language tables in the tpl directory is loaded first, and this is overwritten by any customisation as defined in the custom directory. This allows you to implement full translations, or modify any terms or full translations as supplied with surgeweb. Anything in the tpl directory will be replaced on surgeweb upgrades, none of the language files in the custom directory will be touched during surgemail upgrades.

List of lang files supplied with surgeweb

tpl/lang.dat - Core surgeweb interface files defining "English UK" and "English US". Essential for surgeweb operation.
tpl/lang_demo.dat - Demo partial translations of 16 phrases in 26 languages. Optional, can can be disabled as noted below.
tpl/lang_east.dat - Empty placeholder for full translations of the "eastern" languages.
tpl/lang_euro.dat - Empty placeholder for full translations of the "european" languages.
tpl/lang_asia.dat - Empty placeholder for full translations of the "asian" languages.

Recommended language customisation files

custom/lang.dat - Recommended primary file to customise / add translations (probably all you need for language translation).
custom/lang_mylang1.dat ... - If you are doing full translations for several languages it is nice to keep these as fully specified tables in separate files per language.

Some other important things to know:

In order to apply any changes in the language translation tables you need to restart surgemail.
The default language that surgeweb / user.cgi / surgeplus defaults to can be set using the English language name in the (g_)language_default surgemail.ini setting.
Dependant on how the strings are used in the templates, single quotes will generally need to be encoded as "\'" to prevent javascript errors.
Some string parts get replaced with variables such as username, links etc. These are marked as "%s" in the strings. These can be safely omitted from the translations, if you do not wish to provide these as part of your custom strings.

If you are interested in supplying us with a translation of a non english languages we would be very keen to hear from you :-)

Customising / translating SurgeWeb

I just want to customise the English phrase "x":

Search through tpl/lang.dat to find the phrase(es) in question.
eg. Change "Loading SurgeWeb email ... step n of 3" whilst logging in to "Please wait :-)"

st_loading_init     Loading SurgeWeb email ...
st_loading_usr      Loading SurgeWeb email for %s@%s ...
st_loading_step     step %s of %s

and add that to an appropriate custom/lang.dat file: (note: add   to blank out phrases)

# -----------------
lang:English
# -----------------
st_loading_init     Please wait :-)
st_loading_usr      Please wait :-)
st_loading_step     &nbsp;

I want hide all demo languages

Using the admin interface enable / disable "Hide Language Demos" globally / per domain / per group. This adds the following setting to custom/config*.dat.

  lang_no_demo true

I want to turn a language "x" into a more complete translation

Open tpl/lang.dat and copy just the strings you want to translate or the whole table and copy to custom/lang.dat or say custom/lang_german.dat. Translate all phrases you wish nationalised. Any phrases not translated will get displayed in surgeweb as default English UK. Also at the top add a lang line with 'o'/'+' converted to '*'. This means surgeweb will treat this language a full translation rather than a partial demo translations.
eg. in the case German:

lang:*:German:Deutsch
  
# -----------------
lang:German
# -----------------
st_username         Nutzername
st_password         Passwort
st_log_in           Anmelden
... etc

I want hide several demo languages but keep others

Copy the "lang lines" from tpl/lang.dat to custom/lang.dat and change the 'o' or '+' to '-'.
eg. to remove Chinese and Japanese:

lang:-:Chinese 1:中文（繁體）
lang:-:Chinese 2:中文（简体）
lang:-:Japanese:日本語

I want to change the default language to Xxx

To change the default language you can use the English language text description (as per lang*.dat files) in the surgemail.ini (g_)language_default settings.

eg. to switch to US English default:

g_language_default "English US"

or Japanese

g_language_default "Japanese"

Note: The laguage selection default is cookie based, and will not apply to users that have already connected to surgeweb unless they clear the cookies in their browser cache.

Still to be completed...

So far most of the phrases (approx 800) that have always been defined in the surgeweb templates are now customisable this way.

As noted earlier, for now there are several exceptions, which I will be adding to the language translation capabilities in the near future. These include:

Surgemail serverside generated error codes
A few items in the folder and contacts tree views (notably folder names and group names)
User.cgi / surgeplus generated pages & information. These pages support the translation mechanisms as they have always done, but no work has been completed yet to fully integrate these features with surgeweb. Although the basis for the translation - a cookie named webmail_lang - is fully two way compatible between these translation mechanisms.

Customer contributed translations

Surgeweb language translation files, as contributed by customers.


Search website:

Index