Translator Service

The Translator Service enable you to localize your Templates in different languages.

• Introduction
• Add Language Files
• $template['translator']->trans()

##Introduction

A language file must be a php file with the following structure, i.e. de.php for the locale de (Deutsch):

<?php

if ('á' != "\xc3\xa1") {
    // the language files must be saved as UTF-8 (without BOM)
    throw new \Exception('The language file ' . __FILE__ . ' is damaged, it must be saved UTF-8 encoded!');
}

return array(
    'The Droplet <i>%droplet%</i> does not exists!'
        => 'Das Droplet <i>%droplet%</i> existiert nicht!',
    'User account'
        => 'Benutzerkonto',
    'Username'
        => 'Benutzername',
    'Welcome back, %name%'
        => 'Herzlich willkommen, %name%!'
);

The key of the items in the translation array, i.e. 'Welcome back, %name%' should be in English language and never changed. The key is used to access the translation, php example:

<?php
    echo $template['translator']->trans('Welcome back, %name%',
        array('%name%' => CMS_USER_DISPLAYNAME));
?>

If the actual locale is de, the key will be translated with the value from the de.php above:

`Herzlich willkommen, %name%`

and the placeholder %name% will be replaced with the CMS_USER_DISPLAYNAME, i.e.:

`Herzlich willkommen, Ralf Hertsch`

If the Translator does not find a fitting value for the key, the key itself will be used for the translation.

For example: if the actual locale is nl (Dutch) and there exists no language file nl.php or an existing nl.php does not contain the searched key, the key itself will be used and output (English):

Welcome back, Ralf Hertsch    

###Add Language Files

At initialization the TemplateTools will load all available language files from the paths:

• /kit2/extension/phpmanufaktur/phpManufaktur/Basic/Data/Locale/Metric - contains localized Date and Time, Number and Currency formats.
• /kit2/extension/phpmanufaktur/phpManufaktur/TemplateTools/Data/Locale - contains translations for some basic functions of the TemplateTools, for example the greeting string from the examples in the Introduction.
• /kit2/extension/phpmanufaktur/phpManufaktur/TemplateTools/Data/Locale/Custom - contains your custom translations. The custom files will be loaded behind the language files above and can be used to create additional keys or to overwrite existing keys.

If you perform an update of the TemplateTools, the language files will be overwritten - except of your custom translations. This is important to know - you should never change regular language files, always create a custom file to overwrite the regular language files.

Because the key for the translations is in English language there is no en.php file needed. If you want to change English Translations create a custom en.php and place your translation in the value.

If you want to use Translator also for your Templates, you should create a /locale directory in the root of your Template, use the $template['tools']->addLanguageFiles() function at the top of the index.php to load your language files:

<?php
    // initialize the TemplateTools
    require_once WB_PATH.'/kit2/extension/phpmanufaktur/phpManufaktur/TemplateTools/initialize.php';
    
    // add language files for the template
    $template['tools']->addLanguageFiles(TEMPLATE_PATH.'/locale');
?>

Place all language files you want to use in this /locale directory. Because these language files are loaded behind all other you can use them also to overwrite already existing translation keys.

###trans()

Parameter

• string $key - the string to translate (key)
• array $parameter - optional, default = array(), the placeholders and their values
• string $domain - optional, default = messages (never change this value)
• string $locale - optional, default = null

Usage php

<?php $template['translator']->trans('Welcome back, %name%',
        array('%name%' => CMS_USER_DISPLAYNAME)); ?>

Usage twig (as Filter)

{{ 'Welcome back, %name%'|trans({'%name%':CMS_USER_DISPLAYNAME})  }}

By default the Translator is always using the Locale of the current Page as target for the translation. IF you want to force the Translator to use a specific Locale you can set the $locale parameter:

{{ 'Welcome back, %name%'|trans({'%name%':CMS_USER_DISPLAYNAME}, 'messages', 'fr')  }}

will try to translate the key to French (fr).

⇐ Tools Service | Twig Service ⇒