Internationalization & Localization API
Table of contents:, (*1)
About
This API is a very light weight platform that allows presentation logic (views) to be automatically translated based on user locale (see how are locales detected). In order to achieve this, it expects textual parts of your views to be broken up into fine-grained units (ideally without HTML), each identified by a unique keyword and stored in a topic + locale specific dictionary file (see how are translations stored)., (*2)
, (*3)
This way your HTML view becomes a web of units expected to be translated on compilation, as in example below:, (*4)
<html>
<body>
<h1>__("title")</h2>
<p>__("description")</p>
</body>
</html>
Since the logic of view rendering/compilation is a MVC API's concern, instead of performing keyword replacement with translations based on detected locale in response to be rendered, API provides developers a platform able to automatically detect user locale as well as setting/getting translations based on following steps:, (*5)
API is fully PSR-4 compliant, only requiring PHP 8.1+ interpreter and SimpleXML extension. To quickly see how it works, check:, (*6)
How are locales detected
A locale is understood by this API as a combination of a double digit lowercase ISO language code and a double digit uppercase ISO country code (eg: en_US) joined by underscore. API is able to detect user locale based on following mechanisms:, (*7)
-
header: by value of Accept-Language request header (eg: $_SERVER["HTTP_ACCEPT_LANGUAGE"]= "fr-FR, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5");
-
request: by value of locale querystring parameter (eg: $_GET["locale"] = "fr_FR");
-
session: by value of locale session parameter (eg: $_SESSION["locale"] = "fr_FR");
If locale could not be detected, the default (specific to your application) will be used instead., (*8)
How are translations stored
Translations are expected by API to be stored in JSON files. Each JSON file is found on disk at folder/locale/domain.extension path where:, (*9)
-
folder: folder in your application root where translations are placed. Default: "locale"
-
locale: locale/language in which translations will be looked after. Example: "fr_FR"
-
domain: name of translation file. Default: "messages"
-
extension: translation file extension. Default: "json"
Structure of that file is a dictionary where key is a short keyword that identifies each unit to be translated while value is translation text that will replace keyword when view is compiled. This means for each domain, JSON file must contain same keywords, only with different values specific to locale/language. If a keyword has no matching translation in JSON file, it will appear literally is when view is compiled (aligning with GETTEXT standards)., (*10)
Examples:, (*11)
- locale/en_US/greetings.json:
{"hello":"Hello!", "welcome":"Welcome to my site, %0!"}
- locale/ro_RO/greetings.json:
{"hello":"Salut!", "welcome":"Bun venit pe situl meu, %0!"}
Configuration
To configure this API you must have a XML with a internationalization tag whose syntax is:, (*12)
<internationalization method="..." folder="..." locale="..." domain="..." extension="..."/>
Where:, (*13)
Execution
Now that XML is configured, you can initialize API using Lucinda\Internationalization\Wrapper:, (*14)
$object = new Lucinda\Internationalization\Wrapper(simplexml_load_file(XML_FILE_NAME), $_GET, getallheaders());
This class reads XML and user request, compiles internationalization settings and makes possible to set and get translations based on following public methods:, (*15)
| Method |
Arguments |
Returns |
Description |
| __construct |
\SimpleXMLElement $xml, array $requestParameters, array $requestHeaders |
void |
Compiles internationalization settings based on XML and user requests |
| getReader |
void |
Lucinda\Internationalization\Reader |
Gets instance to use in getting translations |
| getWriter |
void |
Lucinda\Internationalization\Writer |
Gets instance to use in setting translations |
Once instance is made, unit translations can be operated using following methods:, (*16)
Installation
First choose a folder, associate it to a domain then write this command in its folder using console:, (*17)
composer require lucinda/internationalization
Then create a configuration.xml file holding configuration settings (see configuration above) and a index.php file in project root with following code:, (*18)
require(__DIR__."/vendor/autoload.php");
$request = new Lucinda\Internationalization\Wrapper();
$reader = $request->getReader();
Then intervene before response is being rendered to replace unit keywords with translations. For example if your HTML is:, (*19)
<html>
<body>
<h1>__("title")</h2>
<p>__("description")</p>
</body>
</html>
Then this regex will perform perform detected locale-specific translations replacement:, (*20)
$response = preg_replace_callback('/__\("([^"]+)"\)/', function($matches) use ($reader) { return $reader->getTranslation($matches[1]); }, $response);
Unit Tests
For tests and examples, check following files/folders in API sources:, (*21)
Reference Guide
Class Reader
Lucinda\Internationalization\Reader encapsulates retrieving unit translations from storage and defines following relevant public methods:, (*22)
| Method |
Arguments |
Returns |
Description |
| getTranslation |
string $key, string $domain=null |
string |
Gets value of translation based on locale. If none found, value of $key is returned! |
Class Writer
Lucinda\Internationalization\Writer encapsulates adding/updating/deleting unit translations from storage and defines following relevant public methods:, (*23)
| Method |
Arguments |
Returns |
Description |
| setTranslation |
string $key, string $value |
void |
Sets a unit translation for detected locale based on its keyword and value. |
| unsetTranslation |
string $key |
void |
Deletes a unit translation for detected locale based on its keyword |
| save |
void |
void |
Persists changes to JSON translation file. |
Wallogit.com
