< Using the Security Infrastructure

Code Convention >

## 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()`.