sFire PHP Framework

Translation

sFire\Translation\Translation provide a convenient way to retrieve Strings in various languages, allowing you to easily support multiple languages within your application. The translation will search for the language that has been set. If the language is not found, the default text will be shown.

All translation files will be parsed and cached in the "data/cache/translation" directory.

In this section we will handle:

  • Using translation strings as keys
  • Creating translation files
  • Loading translation files
  • Set language
  • Retrieving translation strings
  • Replacing parameters in translation strings
  • Change language for single translation string

Using translation Strings as keys

For applications with heavy translation requirements, defining every string with a "short key" can become quickly confusing when referencing them in the views. For this reason, sFire also provides support for defining translation strings using the "default" translation of the String as the key.

Creating translation files

All translation files are located in the "modules/{YOUR-MODULE-NAME}/translations" folder. The default extension of a translation file is .lg but this can be overwritten in the app.php.

You can choose to put all the translations in one file or to separate them into multiple files. In the example below we will create a single translation file that will be saved in the "modules/app/translations/home" directory with "index.lg" as filename and extension.

Defining languages

The translation language is defined by encapsulating the language between brackets, [ and ]. So for example, the language Dutch can be defined as:

[nl]
Translation strings

All the translation strings will be part of this defined language until a new language is defined or the end of the file is reached. Translation strings are always key/value based, between quotes (single or double) and separated by one or more tabs:

"Hello"         "Hallo"
Example

Below is an example of a translation file with multiple languages:

[nl]
"Hello"         "Hallo"
"Goodbye!"      "Tot ziens!"
"Thank you"     "Bedankt"

[de]
"Hello"         "Hallo"
"Goodbye!"      "Auf Wiedersehen!"
"Thank you"     "Vielen Dank"

[fr]
"Hello"         "Bonjour"
"Goodbye!"      "Au Revoir!"
"Thank you"     "Je vous remercie"

Loading translation files

To load a translation file, you can use the load method in your controller or mapper. This method will parse the translation file in the current module directory. In this example we have a translation file located in "modules/App/translations/home/" as "index.tpl".

Translation :: load('home.index');

As you can see, you can skip the file extension and all the dots will be converted to the current directory separator. On Linux this is a forward slash / but on Windows for example, this will be a back slash \. sFire will load the translation file from within the current module. Therefor, there is no need to define the full path to the translation file.

If you want to translate a viewmodel, you can also give the ViewModel instance as parameter to the load method:

use sFire\MVC\ViewModel;

$view = new ViewModel('home.index');
Translation :: load($view);

Set language

You may change the active language at runtime using the setLanguage method.

Translation :: setLanguage('de');

To change the language for a single translation String, you can use the third parameter of the translate and @translate methods which are described in the "Change language for single translation string" section below.

Retrieving translation strings

To translate a String, you can use the translate in the controller, mapper or the "@translate" method in the viewmodel:

Translation file:

[en]
"welcome"       "Welcome"

Controller:

Translation :: load('home.index');
Translation :: translate('welcome'); //Outputs "Welcome"

View file:

@translate('welcome') //Outputs "Welcome"

Replacing parameters in translation strings

If you wish, you may define place-holders in your translation Strings. All place-holders are prefixed with a "%". For example, you may define a welcome message with a place-holder name.

Translation file:

[en]
"welcome"       "Welcome, %s"

Controller:

Translation :: load('home.index');
Translation :: translate('welcome', ['John']); //Outputs "Welcome, John"

View file:

@translate('welcome', ['John']) //Outputs "Welcome, John"

Note: To use a percentage sign ("%") in your translation, you should escape the character with another "%"

"foo"   "You are 100%% right"

Will output "You are 100% right"

Change language for single translation string

You can change the language for a single translation string without setting a new global language by using the third parameter of the translate or @translate method:

Controller:

Translation :: load('home.index');
Translation :: translate('welcome', null, 'nl');

View file:

@translate('welcome', null, 'nl')