Documentation
Working with application
Language management
The need for multi-lingual websites has become more and more important as sites are welcoming visitors from all around the world more and more frequently.
The toKernel framework recognizes that need and supports several features aimed at making this not only possible but as easy as possible.
Configuring supported languages
The first step for building multi-lingual applications with toKernel is to decide which languages will be supported by the application and then to configure that list in the /application/config/tokernel.ini configuration file.
For the CLI mode see section: [CLI]
cli_allowed_languages=en|fr
For the HTTP mode see section: [HTTP]
http_allowed_languages=en|ru|fr
Allowed languages defined with language prefixes and separated with "|" character. In this example, the CLI mode allowed to run with English and French languages. The full list of language definitions in file /framework/config/languages.ini will be loaded by default into application instance, but if you don't need to support all these languages it is more efficient to make as short as possible, since it will improve the performance of the application both in terms of speed and memory consumption.
The list provided in /application/config/languages.ini overrides the one defined in the framework.
This list is the list of languages returned by the call:
$this->app->allowed_languages()
For example, the contents of your languages.ini could be:
en=English (English)
fr=French (Français)
Organizing translation files
In order to display messages in various languages, you need to provide toKernel with the various translation of these messages in the supported languages. While this can be a long work depending on the number of messages in your application and the number of languages you want to support, the process is nevertheless quite easy.
You create a translation file per language and write the messages you need translated in that language. These translation files have a name in the form language_prefix.ini. So if you have a file called en.ini, you know it will be used to hold messages in English while a file called it.ini will contain messages in Italian.
Several translation files are used by the framework and these are located in various directories.
The /framework/languages/*.ini files will hold translations for messages used by the framework itself and the /application/languages/*.ini files those messages that are global to your application. These will override messages defined in the framework. Additionally each addon may have their own separate languages files since you may find more convenient to manage these messages aside from the global application messages. As for the application messages overriding the framework ones, the addon messages will override those provided at the application level (and at the framework level)
These files are located either in the /framework/addons/addon_name/languages/ directory not in the /application/addons/addon_name/languages/ directory. They also go by the name language_prefix.ini.
Editing translation files
As their name suggest, the translation files obey the .ini format used at other places in toKernel.
The language translation files format is:
; comment
key=message
Blank lines are ignored.
More often, the message is just whatever string is suitable to display, but occasionally, you may need to supply some value that doesn't need to be translated and is not known until the page is generated dynamically, such as the name of a returning visitor.
In this case, the message you put in the translation file will have some placeholders that will be replaced by the parameters you provide when you want to output that message.
For example, a translation file for English could be:
hello=Hello
error_occurred=Error occurred
welcome_user_with_name=Welcome user. Your name is %s and surname is %s!
Creating multi-language pages
A call to the app object language method will return text in the current application language and so will allow to produce text in any of the languages supported by the application.
string language([string $item = NULL, ][string replacement_value_1, ][string replacement_value_2, ][string replacement_value_N] ... );
When called without any argument, the method will return the current language prefix. This can be used to set the value of the "lang" attribute of any html tag using this attribute, the most come one being the </tag>.</p> <p>For example, to let the browser know which is the page default language, you could write:</p> <code><tag>
in your view or template.
When given one argument, this method will retrieve and return the string whose key is equal to the argument in the translation file for the current language.
// Returns message Error occurred
$error_message = $this->app->language('error_occurred');
If the message has one or more placeholders, these will be replaced by the value of second, third.. arguments.
Using the above example translation file, the following code:
$welcome_message = $this->app->language('welcome_user_with_name', 'John', 'Smith');
will return: "Welcome user. Your name is John and surname is Smith!"
The application current language can be changed easily by invoking the app object set_language method.
void set_language(string $lp)
Sets the application current language to the language having $lp for prefix.
For example:
$this->app->set_language('de');
will set the current language to German (Deutsch). After this call, invocation of the language method will return messages taken from the de.ini file.
This allows to include messages in various languages on the same page. It is recommended to set the surrounding tag "lang" attribute to the correct value.
Missing items
Translating an application from one language to one or several others can be a tedious and lengthy process. Delays may be introduced as well because of the limited availability of translators for some languages.
In order to avoid having a missing translation delaying the release of urgent bugs fixes or other similar cases, toKernel language support will gracefully degrade when a translation is missing for a given language.
The application configuration tokernel.ini file let you define your application default language. Whenever the item passed to the app->language method is missing in the current language translation file, the framework will take the message from the default language file.
If the item is also missing from that default language translation file, a warning error will be triggered when running in development mode. In production mode, the item itself will be returned surrounded in curly braces.
In our example, the call:
$this->language('bonjour');
will return the string "{bonjour}"
Using other addons translations
Duplicating code is never a good idea and the same is true for translation file items. You should try to avoid having the same key=message duplicated in several translation files as much as possible.
However, to make this practical and avoid having all messages ending up in the application global translation files, an addon needs to get access to keys from other addons translation files.
This can be done easily by using:
$this->lib->addons->other_addon_name->language('item');
See also: Language class library