The translation handler

blaze comes with a translation handler which is used internally to translate the backend. It is additionally needed for translating plugins.

The translation handler relies on easily editable json files. The basic files for the backend are located in the folder 'locale' within the main 'blaze' folder.

JSON syntax

Whenever you make a change to the language files, be aware that the files have to consist of valid JSON. You can read more about JSON at w3schools. Make sure to put a backslash in front of the double-quotes which are meant to be contained within a language string.

Plugin development

When developing plugins, you could use the translation handler to provide easily translatable views. Just create a folder 'locale' within your plugin's main folder and create language files according to the given conventions.

If a plugin does contain translation files within a 'locale' folder, blaze will automatically load the strings from those files. If you do not provide a locale file for the language that is setup in the backend, blaze will look for the fallback 'en.json' file.

There is a usage example at the bottom of this page.

Available functions

blaze holds an instance of the translation handler which does translate all strings to the language which is setup in the backend. The instance is available as

    $blaze->locale

Remember that the plugins themselves do not have access to blaze, they need to instantiate a new translation handler in order to use it. See the tutorial for an example for this.

In the plugin's backend views you can use the instance which is included in the main blaze object. Keep in mind that the views will probably be using twig as templating engine, you would have to access the functions with a different syntax:

    {{ blaze.locale.function() }}

where function() would of course be one of the following ones. There are several methods you may use to interact with the translation handler.

    $blaze->locale->setLanguage($language);

If you want to change the used language from the one that is set in main configuration, you can do this at runtime. $language has to be an existing language file's id (like 'de' for German).

    $blaze->locale->getAvailableLanguages();

This method will return an array holding the available languages.

    $blaze->locale->getTranslatedStringIds();

This method returns an array holding all the ids of the available translated strings which are ready for usage in $blaze->locale->translate(). See the usage example below to learn about the string id.

    $blaze->locale->translate($stringid);

This is the method to use in order to get the translated string. $stringid is mandatory and should be a string. See the usage example below to learn about the string id.

    $blaze->locale->stringExists($stringid);

A simple helper method to see if a string does exists in the available translated strings. $stringid is mandatory and should be a string. See the usage example below to learn about the string id.

Usage example

Translation file

This is how a translation file should basically look like.

    {
        "languagedetails": {
            "name" : "English",
            "id" : "en"
        },
        "mystrings": {
            "teststring" : "translation"
        }
    }

This translation file (which must in this case be named 'en.json' because of the "id" contained in "languagedetails"), we could access the translated strings like this:

    $translation = $blaze->locale->translate('mystrings.teststring');

$translation would now hold 'translation', coming from the translation file.

Please take a look at the plugin development tutorial in which we'll also setup this translation component.

Using the translation handler in your plugin

If you have properly setup your plugin and your locale files, you can instantiate the backend handler within your plugin class like this:

    <?php
        namespace blaze\plugins\mycoolplugin;

        use \blaze\src\SettingsHandler;
        use \blaze\src\TranslationHandler;

        class mycoolplugin extends \blaze\src\prototype\Plugin
        {
            function __construct()
            {
                // Load blaze's settings
                $blazesettings = new SettingsHandler();

                // Instantiate the translation handler with the language that is setup in the main configuration
                $this->locale = new TranslationHandler($blazesettings->get('ui.language'));
            }

            public function helloWorld()
            {
                echo $this->locale->translate('mystrings.helloworld');
            }
        }
    ?>

The UI action handler does not need to instantiate the translation component because it holds an instance of blaze. See the example:

    <?php
        namespace blaze\plugins\mycoolplugin;

        class uiactions extends \blaze\src\prototype\UIActionHandler
        {
            public function helloWorld()
            {
                echo $this->blazeinstance->locale->translate('mystrings.helloworld');
            }
        }
    ?>