5. Internationalization

5.1. Translations

Texts to be translated can be found in:

Smarty templates (see Section 17.2, “Internationalization”)
Client and server .ini files and map files (see Chapter 4, Configuration Files)
Client and server PHP code

In the last case, the script which finds strings to be translated (see Section 16.1.2, “PO Templates”) looks for calls to gt() functions. There are two different gt() functions:

I18n::gt(): tries to translate the string given as argument and returns the translation. This function assumes that string is UTF-8 encoded and returns a string ready for output (see Section 5.2, “Character Set Encoding”). It can be used on client side only
I18nNoop::gt(): does nothing during runtime ("noop" stands for "no operations"). Call to this function is only needed to indicates that the string must be translated. This function can be used on client and server side

Below is an example on how to use I18nNoop::gt():

/**
 * Example for use of I18n gt() functions (client side)
 */
class ClientMyPlugin extends ClientPlugin
                     implements GuiProvider, ServerCaller {

    // ...
    
    public function initializeResult($myPluginResult) {
        
        // Retrieves message
        $this->message = $myPluginResult->message;
    }

    public function renderForm(Smarty $smarty) {
  
        // Translation and display
        $smarty->assign('message', I18n::gt($this->message));
    }
}

/**
 * Example for use of I18n gt() functions (server side)
 */
class ServerMyPlugin extends ClientResponderAdapter {

    // ...

    public function handlePreDrawing($request) {
        
        $myPluginResult = new MyPluginResult();

        // Message must be translated, but not now!
        $myPluginResult>message = I18nNoop::gt('hello, world');
        
        return $myPluginResult;
    }
}

In this example, message sent by server has to be translated. But as translation process is always done on client, we only indicates to the script that there is a text to add to the translation template.

5.2. Character Set Encoding

As already described in Section 16.2, “Character Set Encoding Configuration”, character set encoding is done using Encoder set of classes. It uses functions Encoder::encode() and Encoder::decode():

Encoder::encode($text, $context): converts text from context's character set to CartoWeb's internal character set (UTF-8)
Encoder::decode($text, $context): converts text from CartoWeb's internal character set (UTF-8) to context's character

Context can be either 'config' or 'output', default is 'output'. Corresponding configuration is set in server.ini and client.ini (see Section 16.2, “Character Set Encoding Configuration”).

Function Encoder::encode() must be used in the following situation:

on client or server when reading a text from a configuration file:
```
$encodedText = Encoder::encode($readText, 'config');
```

Function Encoder::decode() must be used in the following situations:

on client when outputing a text without calling I18n::gt():
```
$textToDisplay = Encoder::decode($encodedText);
```
on client or server when calling an external module, eg. Mapserver for a query:
```
$textToUseInMapserver = Encoder::decode($encodedText, 'config');
```

Note that function I18n::gt() takes an encoded text as argument and already prepares texts for output. It means you don't need to call Encoder::decode() after a call to I18n::gt().