I18n
Adding internationalization capabilities
Table of Contents
What's I18n
I18n means internationalization. There are 18 characters between the first letter of the word and the last one, so there is an i followed by 18 characters and a n.
The concept is really simple: To provide an application a way to show the same content in different languages.
Lion offers a set of libraries perfectly integrated within the rest of the framework to bring our applications with I18n capabilities easily, so we just need to define our I18n language-specific literals within separate files by following some naming-conventions and let the framework do the rest.
Define I18n literals
We can define literals for a concrete language by just following a simple naming convention:
- Literals for each language must be contained in a separate folder contained within the libs/language directory. i.e. english language literals must be defined inside the libs/language/en directory.
- Literals must be set in different files. Those files must have the name of the controller code followed by the .ini extenssion. i.e. literals to be used within the myControllerCode controller must be defined in the libs/language/en/myControllerCode.ini file.
Of course, Lion is opened to set whatever way to retrieve language literals (from database, from other file naming convention, from memcache, ...), however this naming convention is the result of the configuration that Lions offers by default.
i.e., we can define literals to each languages by just creating different directories (one per each language with the 2 letter iso code of each language) and setting-up .ini files in each one:
English literals (to be defined in libs/language/en/myControllerCode.ini)
Spanish literals (to be defined in libs/language/es/myControllerCode.ini)
The Resource Manager
Language literals are also known as string resources. The __ResourceManager is the class in charge of serve I18n literals.
The resource manager has a really useful method to do that: __ResourceManager::getResource()
i.e.
<?php
//get the resource manager associated to our application:
->getResourceManager();
//get the english welcome literal:
$welcome_literal = $resource_manager->getResource('welcome', 'en')
->getValue();
The Locale Negociator
Lion negociates at the very beginning of the request the browser configured locale.
This locale is taken into account if the language is already supported by the application. i.e., if we support both english and spanish, and a browser has the locale es_ES, the application will take into account it.
However, if the client locale is not supported by the application, it will use the default one (configured as part of the I18n.xml file).
In this case, if we do not specify a language to retrieve literals from the Resource Manager, the negociated one will be used instead of:
<?php
//get the resource manager associated to our application:
->getResourceManager();
//get the negociated language welcome literal by just
//ommiting the language parameter to get the literal from:
$welcome_literal = $resource_manager->getResource('welcome')
->getValue();
I18n and templates
I18n is also perfectly integrated within template views
We are able to just define placeholders with the same name of the literal key. The template based view will recognize them and set the I18n literals.
i.e. myControllerCode.tpl template:
...
</head>
<body>
<!-- show the welcome message: -->
{$welcome}
...
Language literals will be set according to the current negociated language
However, another way to set literals into templates is by ussing the resource component:
i.e.
...
</head>
<body>
<!-- show the welcome message: -->
<
comp:
resource key=
"welcome"/>
...
Parametrized literals
Sometime, we need to set valueholders inside I18n literals.
Imagine the following message: Welcome Antonio to our web application. This message could be in spanish like Bienvenido a nuestra aplicacion web, Antonio.
So, we may need to define placeholders inside the I18n literals to be replaced by dynamic values in runtime
To do that, we are able to define placeholders enclosed by curly brakets (i.e. {0}, {1}, {2}, ...)
English literals (to be defined in libs/language/en/myControllerCode.ini)
welcome = "Welcome {0} to our web application"
Spanish literals (to be defined in libs/language/es/myControllerCode.ini)
welcome = "Bienvenido a nuestra aplicacion web, {0}"
So, we just need to set the paremeters in the resource by following the same order they are defined as placeholders in the I18n literals: i.e.
<?php
//get the resource manager associated to our application:
->getResourceManager();
//get the welcome literal and set Antonio to the {0} placeholder:
$welcome_literal = $resource_manager->getResource('welcome')
->setParameters(array('Antonio'))
->getValue();
