Localization and translation

Introduction

In any application, there is a need to make the application multilingual. Bow implements a simple translation system.

Configuration

To use the translation system, you must first consider the configuration found in the config/trans.php file. In this file, the default language is French, so 'lang' => 'fr'.

Your application's translations are stored in the lang folder. These are php files that return an array. As you can see, there is an fr folder and an en folder. These are the folders for each language: fr for French and en for English. If there were another language, for example Spanish, the folder would be named es.

/lang
  /en
    messages.php
  /fr
    messages.php

File structure

All language files return an array of keyed strings. Each key represents a specific translation.

For example:

lang/en/messages.php

return [
  'welcome' => 'Welcome to our application'
];

Configuring the locale

Your application's default language is stored in the config/trans.php configuration file. Of course, you can change this value to suit your application's needs.

You can also change the active language at runtime using the setLocale method on the Bow\Translate\Translator class:

routes/app.php

use Bow\Translate\Translator;

$router->get('docs/:locale', function ($locale) {
  Translator::setLocale($locale);
  //
});

Fallback language

You can configure a fallback language that will be used when the active language does not contain a given translation string. Like the default language, the fallback language is also configured in the config/trans.php configuration file:

config/trans.php

'lang' => 'en',

Retrieving translation strings

You can extract lines from language files using the trans or t helper function. The t method accepts the file and the key of the translation string as its first argument. For example, let's retrieve the welcome translation string from the lang/messages.php language file:

echo t('messages.welcome');

// Or
echo trans('messages.welcome');

// Or
use Bow\Translate\Translator;

echo Translator::translate('messages.welcome');

Determining the current locale

You can use the getLocale and isLocale methods on the Translator class or via the trans helper to determine the current locale or check whether the locale matches a given value:

use Bow\Translate\Translator;

$locale = Translator::getLocale();

if (Translator::isLocale('en')) {
 //
}

Via the trans helper

$locale = trans()->getLocale();

if (trans()->isLocale('en')) {
 //
}

Missing translations

If the specified translation string does not exist, the t function will return the translation string key. So, using the example above, the t function would return messages.welcome if the translation string does not exist.

Replacing parameters in translation strings

If you wish, you can define placeholders in your translation strings. All placeholders are enclosed in {}. For example, you can define a welcome message with a placeholder name:

'welcome' => 'Welcome, {name}',

To replace the placeholders when retrieving a translation string, pass an array of replacements as the second argument to the t or trans function:

echo t('messages.welcome', ['name' => 'Galy']);

Pluralization

Pluralization is a complex problem, because different languages have a variety of complex rules for pluralization. By using a "pipe" character (|), you can distinguish the singular and plural forms of a string:

"names" => "C'est un utilisateur|Ce sont des utilisateurs",

After defining a translation string with pluralization options, you can use the t or trans function. In this example, since the number is greater than one, the plural form of the translation string is returned:

echo t("messages.names", count($names) > 1);

Pluralization with replacement

With the replaced data:

"names" => "Bonjour {name}|Bonjour à tous",

echo t("messages.names", ["name" => "Newt"], count($names) == 1);
// => Bonjour Mewt

Is something missing?

If you run into problems with the documentation or have suggestions to improve the documentation or the project in general, please open an issue for us, or send a tweet mentioning the Twitter account @bowframework or directly on github.