Each text or string that you want to translate is associated to a key, a code. These associations are placed in "properties files". Each properties file is associated to a language and character encoding. The default language and character encoding are configured in the config file of your application.

$lang = $GLOBALS['gJConfig']->locale;

To be able to retrieve a string in the current language, you only have to call jLocale::get('LocaleSelector'), or in the templates use the @LocaleSelector@ syntax (see the page about templates).

These are files containing translations. They are located in the locales directory of the modules. This directory has a specific organization. It has sub-repositories for each language. Example: locales/fr_FR/, locales/en_US/, etc. And in each of these sub-directories there are properties files corresponding to the language.

File names ¶

File contents ¶

title.offlineElements = elements to check
title.onlineElements = online elements

buttons.save = Save
buttons.ok=Ok
buttons.cancel=Cancel
buttons.search=Search

title.offlineElements = éléments à traiter
title.onlineElements = éléments en ligne
buttons.save = Enregistrer
buttons.ok=Valider
buttons.cancel=Annuler
buttons.search=Rechercher

intro=this is a very very\
long text in\
several lines
foo=bar

intro=this is a very very\nlong text in\nseveral lines
foo=bar

foo= \w

To retrieve a string, you have to use the get static method of jLocale. This method accept as the first argument a locale selector, which has the following structure : module~filecode.keystring. the "module~" part optional if this is a file from the current module.

For example, to retrieve the value of buttons.save in foo.ISO-8859-1.properties in the "bar" module :

  $string = jLocale:get("bar~foo.buttons.save");

In a template, this would be for example :

  <input type="button" value="{@bar~foo.buttons.save@}" />

It could be useful to have localized string with dynamic parameters.

For example, you want to write this string:

   You will go on the http://foo.com web site and you will click on the 'car' category.

But you would like to indicate dynamically the url of the web site and the name of the category. You can then pass this dynamic values as parameters to jLocale:

  $string = jLocale::get("bar~foo.sentence", array('http://foo.com', 'car'));

And in the properties file, you have to put a "%s" where you want to insert this dynamic values:

   sentence = You will go on the %s web site and you will click on the '%s' category.

This string is parsed by the sprintf function. So you should follow the syntax accepted by sprintf. For example, the order of the parameter is important.

In particularly, in some language, perhaps the translation causes a change in the order of parameters. But you won't pass the parameters in a different order. So you will use the syntax %x$s where x is the order number. For example, you could have this sentence:

   sentence = Click on the %s section, when you go on the %s web site.

But in an other language, the translator would like to change the order of the parameters (eg. the first parameter in the sentence will be the url web site, not the section name). So for example, in french, he could translate like this:

   sentence = Vous allez sur le site %2$s et vous cliquez sur la rubrique %1$s

So the first parameter will replace "%1$s", the second parameter will replace "%2$s" and so on.

Note that in template, you can use the "@foo@" syntaxe to indicate parameters. So you have to use the "jlocale" plugin:

   <p>{jlocale "bar~foo.sentence", array('http://foo.com', 'car')}</p>

Jelix provide a plugin for the coordinator, which allow to change dynamically the language of the web site. This is the "autolocale" plugin (in lib/jelix/plugins/coord/). (see plugins/coord)

The plugin look at the url, and check if there is a specific parameter which indicate the new lang to use (by default, this parameter is "lang"). The code of the new lang is then stored in session, and then the web site will be displayed with this language for the rest of the visit (until there is a new lang parameter with a different language code).

Note that the "locale" configuration variable is also changed, but only dynamically at each request. The configuration file is not modified. So it is totally transparent for you. To know the current locale, you just have to do :

  $lang = $GLOBALS['gJConfig']->locale;

To use the plugin, copy the file lib/jelix/plugins/coord/autolocale/autolocale.coord.ini.php.dist in the var/config/ directory, by renaming it to autolocale.coord.ini.php.

In this file, two parameters are important :

enableUrlDetection= on
urlParamNameLanguage=lang
availableLanguageCode = fr_FR,en_US

You should have of course to activate the language detection in the url. So you set enableUrlDetection to "on". In availableLanguageCode, you put all language code available in your web site. And the urlParamNameLanguage variable should content the name of the url parameter which wil contain the new language code to use.

So in your template, you can put some link to allow the user to change the language:

  <a href="index.php?lang=en_EN">english</a>
  <a href="index.php?lang=fr_FR">français</a>

Now you can activate the plugin. Inside the configuration file of your application, put in the [plugins] section:

[plugins]
autolocale = autolocale.coord.ini.php

And that's all. Your application supports multiple language at the same time. Now you just have to write properties file for each language.

The autolocale plugin allows to detect automatically the lang of the user, by looking at the http headers sent by the browser.

After installing the plugin (see above), set the useDefaultLanguageBrowser variable to "on" in the configuration file of the plugin.

So, when the user arrives on your web site for the first time, the plugin look at http headers to see which language the user use in his browser, and then activate the corresponding language in jelix. (of course, only for language which are listed in availableLanguageCode).