TooBasic: Languages

Languages?

One of the functionalities TooBasic provides is the ability to translate text across controllers, templates, services, etc. In other words, you can provide a page that says Welcome to our site and Bienvenido a nuestro sitio based on the current language.

How to configure it

The first thing you would want to do is to set the default language to use. If you haven't done it yet, it will be en_us and it may be what you need, otherwise can add something like this in your site's configuration at ROOTDIR/site/config.php:

$Defaults[GC_DEFAULTS_LANG] = 'es_ar';

In the example, you'll be setting the default language as Spanish, specifically the Spanish spoken in Argentina.

Adding translations

Translations are based on keys, which means somewhere in your site there's a key that points to a translated text. Let's say we're going to use a key called welcome_site to translate into those texts we've mentioned at the beginning of this page. The first thing to do is to create a file at ROOTDIR/site/langs/en_us.json with something like this inside:

{
    "keys": [{
        "key": "welcome_site",
        "value": "Welcome to our site"
    }]
}

Also, we're going to create a file at ROOTDIR/site/langs/es_ar.json for Spanish translations:

{
    "keys": [{
        "key": "welcome_site",
        "value": "Bienvenido a nuestro sitio"
    }]
}

This configurations provide the flexibility to welcome user in your page based on the current language.

Using translations

Now we know how to configure translations, but how do we use them? Let's say you want to use this new translation key inside a controller and assign it to some view value, for that you may write something like this:

    protected function basicRun() {
        . . .

        $this->assign('welcome', $this->tr->welcome_site);

        . . .

        return $this->status();
    }

As you can see, the magic property tr allows you to use your translation key directly. This is also available inside models, services, emails and others.

Now if you're already inside a template (for Smarty templates), you may write something like this:

    <body>
        <header>
            <h2>{$tr->welcome_site}</h2>
        </header>

        . . .

Advanced

All of this may seem easy, but the problem comes when your translation have variable pieces in the middle of it, and those pieces are in different places depending on your language. For example, if you want to formally address a person by its last name, in English and Spanish it would mean to set a translation key for Mr. and Sr., and then paste it before the last name. But if you also serve your site in Japanese, the translated key goes after the last name.

In these cases is where you need to make an advanced usage of translation keys. To handle our example let's write something like this at ROOTDIR/site/langs/en_us.json

{
    "keys": [{
        "key": "mr_name",
        "value": "Mr. %name%"
    }]
}

And somethig like this at ROOTDIR/site/langs/ja_jp.json

{
    "keys": [{
        "key": "mr_name",
        "value": "%name%さん"
    }]
}

Then you can write something like this inside a controller:

        . . .
        $this->assign('welcome', $this->tr->mr_name('name', $user->last_name));
        . . .

Or:

        . . .
        $this->assign('welcome', $this->tr->mr_name([
            'name' => $user->last_name
        ]));
        . . .

Or even in a view:

    <body>
        <header>
            <h2>{$tr->welcome_site}, {$tr->mr_name('name', $usr_last_name)}</h2>
        </header>

        . . .

Precompiled translations

As you may be expecting from TooBasic, not only the site can define translation keys, also each module/plugin may define its own translation keys or even override some. This is something interesting and useful, but it might also become a burden for your site's performance because if you translate at least one key, it will load and analyze all translation files for the current language.

Fortunately, this happens for the first translation, the rest will use what is loaded. Nonetheless each and every request were there's a translation will trigger this loading process.

To reduce the performance problem, TooBasic provides a way to pre-analyze all language specifications and store them as one per each language. This is not a mandatory functionality, but if you're having problems with performance, it may help a little.

Compilation

The first thing to do is to precompile all languages and for that TooBasic provides a shell tool called translate that can be used in this way:

$ php shell.php tool translate --compile

This tool will load and analyze each translation file for every language and generate a single file per language and store them at ROOTDIR/cache/langs/.

Note: If you are using precompiled translations, remember to run this tool everytime you install or remove a module and when you add, remove or change translations in your site.

Configuration

Once you have your language configuration files compiled, you must add something like this to your site's configuration file:

$Defaults[GC_DEFAULTS_LANGS_BUILT] = true;

This configuration tells TooBasic to use precompiled files instead of normal translation files.

Suggestions

You may also visit these documentation pages:

Languages