Next Previous Contents

7. Using Language Support

7.1 Overview

phpGroupWare is built using a multi-language support scheme. This means the pages can be translated to other languages very easily. Translations of text strings are stored in the phpGroupWare database, and can be modified by the phpGroupWare administrator.

7.2 How to use lang support

The lang() function is your application's interface to phpGroupWare's internationalization support.

While developing your application, just wrap all your text output with calls to lang(), as in the following code: 

  $x = 42;
  echo lang("The counter is %1",$x)."<br>";
This will attempt to translate "The counter is %1", and return a translated version based on the current application and language in use. Note how the position that $x will end up is controlled by the format string, not by building up the string in your code. This allows your application to be translated to languages where the actual number is not placed at the end of the string.

When a translation is not found, the original text will be returned with a * after the string. This makes it easy to develop your application, then go back and add missing translations (identified by the *) later.

Without a specific translation in the lang table, the above code will print: 

The counter is 42*<br>
If the current user speaks Italian, they string returned may instead be: 
il contatore è 42<br>

The lang function

lang($key, $m1="", $m2="", $m3="", $m4="", $m5="", 
             $m6="", $m7="", $m8="", $m9="", $m10="")
$key

is the string to translate and may contain replacement directives of the form %n.

$m1

is the first replacement value or may be an array of replacement values (in which case $m2 and above are ignored).

$m2 - $m10

the 2nd through 10th replacement values if $m1 is not an array.

The database is searched for rows with a lang.message_id that matches $key. If a translation is not found, the original $key is used. The translation engine then replaces all tokens of the form %N with the Nth parameter (either $m1[N] or $mN).

Adding translation data

An application called Transy is being developed to make this easier, until then you can create the translation data manually.

The lang table

The translation class uses the lang table for all translations. We are concerned with 4 of the columns to create a translation:

message_id

The key to identify the message (the $key passed to the lang() function). This is written in English.

app_name

The application the translation applies to, or common if it is common across multiple applications.

lang

The code for the language the translation is in.

content

The translated string.

lang.sql

Currently all applications, and the core phpGroupWare source tree have a lang.sql file. This is the place to add translation data. Just add lines of the form: 

REPLACE INTO lang (message_id, app_name, lang, content) 
VALUES( 'account has been deleted','common','en','Account has been deleted');
translating the content to reflect the message_id string in the lang language. If the string is specific to your application, put your application name in for app_name otherwise use the name common. The message_id should be in lower case for a small increase in speed.

7.3 Common return codes

If you browse through the phpGroupWare sources, you may notice a pattern to the return codes used in the higher-level functions. The codes used are partially documented in the doc/developers/CODES file.

Codes are used as a simple way to communicate common error and progress conditions back to the user. They are mapped to a text string through the check_code() function, which passes the strings through lang() before returning.

For example, calling 

echo check_code(13);
Would print 
Your message has been sent
translated into the current language.

Next Previous Contents