Download the PHP package lucinda/internationalization without Composer

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:

• 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.

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:

• 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).

Examples:

• locale/en_US/greetings.json:

• locale/ro_RO/greetings.json:

Configuration

To configure this API you must have a XML with a internationalization tag whose syntax is:

Where:

• method: (mandatory) identifies how locales are detected (see how are locales detected). Can be: header, request, session!
• folder: (optional) folder in your application root where translations are placed (see how are translations stored). If not set, "locale" is assumed!
• locale: (mandatory) default locale in which translations will be looked after (see how are translations stored). Eg: en_US
• domain: (optional) name of translation file (see how are translations stored). If not set, "messages" is assumed!
• extension: (optional) translation file extension (see how are translations stored). If not set, "json" is assumed!

Execution

Now that XML is configured, you can initialize API using Lucinda\Internationalization\Wrapper:

This class reads XML and user request, compiles internationalization settings and makes possible to set and get translations based on following public methods:

Once instance is made, unit translations can be operated using following methods:

• getReader: gets a detected locale
• getWriter: gets a Lucinda\Internationalization\Writer object able to save/delete translations from detected locale using

Installation

First choose a folder, associate it to a domain then write this command in its folder using console:

Then create a configuration.xml file holding configuration settings (see configuration above) and a index.php file in project root with following code:

Then intervene before response is being rendered to replace unit keywords with translations. For example if your HTML is:

Then this regex will perform perform detected locale-specific translations replacement:

Unit Tests

For tests and examples, check following files/folders in API sources:

• test.php: runs unit tests in console
• unit-tests.xml: sets up unit tests
• tests: unit tests for classes from src folder

Reference Guide

Class Reader

Lucinda\Internationalization\Reader encapsulates retrieving unit translations from storage and defines following relevant public methods:

Class Writer

Lucinda\Internationalization\Writer encapsulates adding/updating/deleting unit translations from storage and defines following relevant public methods: