PHPackages lucinda/internationalization - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Localization & i18n](/categories/localization) 4. / 5. lucinda/internationalization ActiveLibrary[Localization & i18n](/categories/localization) lucinda/internationalization ============================ High-performance API performing internationalization and localization for PHP applications via JSON files v5.0.1(3w ago)023.6k—0%22MITPHPPHP ^8.1 Since Feb 11Pushed 3w ago1 watchersCompare [ Source](https://github.com/aherne/php-internationalization-api)[ Packagist](https://packagist.org/packages/lucinda/internationalization)[ Docs](https://github.com/aherne/php-internationalization-api)[ RSS](/packages/lucinda-internationalization/feed)WikiDiscussions master Synced today READMEChangelogDependencies (3)Versions (31)Used By (2) Internationalization & Localization API =========================================== [](#internationalization--localization-api) Table of contents: - [About](#about) - [How Are Locales Detected](#how-are-locales-detected) - [How Are Translations Stored](#how-are-translations-stored) - [Configuration](#configuration) - [Execution](#execution) - [Installation](#installation) - [Unit Tests](#unit-tests) - [Reference Guide](#reference-guide) About ----- [](#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](#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](#how-are-translations-stored)). [![diagram](https://camo.githubusercontent.com/a791432e23dcf3d69173c6cace095fc87107338cc1d4da0f38092cd20d3a631e/68747470733a2f2f7777772e6c7563696e64612d6672616d65776f726b2e636f6d2f696e7465726e6174696f6e616c697a6174696f6e2d6170692e737667)](https://camo.githubusercontent.com/a791432e23dcf3d69173c6cace095fc87107338cc1d4da0f38092cd20d3a631e/68747470733a2f2f7777772e6c7563696e64612d6672616d65776f726b2e636f6d2f696e7465726e6174696f6e616c697a6174696f6e2d6170692e737667) This way your HTML view becomes a web of units expected to be translated on compilation, as in example below: ``` __("title") __("description") ``` 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: - **[configuration](#configuration)**: setting up an XML file where API is configured for locale detection and translations storage - **[execution](#execution)**: creating a [Lucinda\\Internationalization\\Wrapper](https://github.com/aherne/php-internationalization-api/blob/master/src/Wrapper.php) instance based on above, to use in getting/setting translations by keyword API is fully PSR-4 compliant, only requiring PHP 8.1+ interpreter and SimpleXML extension. To quickly see how it works, check: - **[installation](#installation)**: describes how to install API on your computer, in light of steps above - **[unit tests](#unit-tests)**: API has 100% Unit Test coverage, using [UnitTest API](https://github.com/aherne/unit-testing) instead of PHPUnit for greater flexibility - **[example](https://github.com/aherne/php-internationalization-api/blob/master/tests/WrapperTest.php)**: shows a deep example of API functionality based on unit test for [Lucinda\\Internationalization\\Wrapper](https://github.com/aherne/php-internationalization-api/blob/master/src/Wrapper.php) ### How are locales detected [](#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 [](#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: ``` {"hello":"Hello!", "welcome":"Welcome to my site, %0!"} ``` - locale/ro\_RO/greetings.json: ``` {"hello":"Salut!", "welcome":"Bun venit pe situl meu, %0!"} ``` Configuration ------------- [](#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](#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](#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](#how-are-translations-stored)). Eg: en\_US - *domain*: (optional) name of translation file (see [how are translations stored](#how-are-translations-stored)). If not set, "messages" is assumed! - *extension*: (optional) translation file extension (see [how are translations stored](#how-are-translations-stored)). If not set, "json" is assumed! Execution --------- [](#execution) Now that XML is configured, you can initialize API using [Lucinda\\Internationalization\\Wrapper](https://github.com/aherne/php-internationalization-api/blob/master/src/Wrapper.php): ``` $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: MethodArgumentsReturnsDescription\_\_construct\\SimpleXMLElement $xml, array $requestParameters, array $requestHeadersvoidCompiles internationalization settings based on XML and user requestsgetReadervoid[Lucinda\\Internationalization\\Reader](https://github.com/aherne/php-internationalization-api/blob/master/src/Reader.php)Gets instance to use in getting translationsgetWritervoid[Lucinda\\Internationalization\\Writer](https://github.com/aherne/php-internationalization-api/blob/master/src/Writer.php)Gets instance to use in setting translationsOnce instance is made, unit translations can be operated using following methods: - **getReader**: gets a [Lucinda\\Internationalization\\Reader](#class-reader) object able to retrieve translations from [storage](#how-are-translations-stored) based on [detected locale](#how-are-locales-detected) - **getWriter**: gets a [Lucinda\\Internationalization\\Writer](https://github.com/aherne/php-internationalization-api/blob/master/src/Writer.php) object able to save/delete translations from [storage](#how-are-translations-stored) based on [detected locale](#how-are-locales-detected) using Installation ------------ [](#installation) First choose a folder, associate it to a domain then write this command in its folder using console: ``` composer require lucinda/internationalization ``` Then create a *configuration.xml* file holding configuration settings (see [configuration](#configuration) above) and a *index.php* file in project root with following code: ``` 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: ``` __("title") __("description") ``` Then this regex will perform perform detected locale-specific translations replacement: ``` $response = preg_replace_callback('/__\("([^"]+)"\)/', function($matches) use ($reader) { return $reader->getTranslation($matches[1]); }, $response); ``` Unit Tests ---------- [](#unit-tests) For tests and examples, check following files/folders in API sources: - [test.php](https://github.com/aherne/php-internationalization-api/blob/master/test.php): runs unit tests in console - [unit-tests.xml](https://github.com/aherne/php-internationalization-api/blob/master/unit-tests.xml): sets up unit tests - [tests](https://github.com/aherne/php-internationalization-api/tree/v3.0.0/tests): unit tests for classes from [src](https://github.com/aherne/php-internationalization-api/tree/v3.0.0/src) folder Reference Guide --------------- [](#reference-guide) ### Class Reader [](#class-reader) [Lucinda\\Internationalization\\Reader](https://github.com/aherne/php-internationalization-api/blob/master/src/Reader.php) encapsulates retrieving unit translations from [storage](#how-are-translations-stored) and defines following relevant public methods: MethodArgumentsReturnsDescriptiongetTranslationstring $key, string $domain=nullstringGets value of translation based on locale. If none found, value of $key is returned!### Class Writer [](#class-writer) [Lucinda\\Internationalization\\Writer](https://github.com/aherne/php-internationalization-api/blob/master/src/Writer.php) encapsulates adding/updating/deleting unit translations from [storage](#how-are-translations-stored) and defines following relevant public methods: MethodArgumentsReturnsDescriptionsetTranslationstring $key, string $valuevoidSets a unit translation for detected locale based on its keyword and value.unsetTranslationstring $keyvoidDeletes a unit translation for detected locale based on its keywordsavevoidvoidPersists changes to JSON translation file. ### Health Score 58 — FairBetter than 98% of packages Maintenance94 Actively maintained with recent releases Popularity24 Limited adoption so far Community15 Small or concentrated contributor base Maturity83 Battle-tested with a long release history Bus Factor1 Top contributor holds 97% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~104 days Recently: every ~226 days Total 30 Last Release 26d ago Major Versions v2.0.7 → v3.0.02020-02-01 v3.0.3 → v4.0.02021-12-30 v3.0.x-dev → v4.1.02022-06-12 v2.0.x-dev → v4.1.12026-01-16 v4.1.2 → v5.0.12026-06-07 PHP version history (3 changes)v2.0.7PHP ^7.1 v4.0.0PHP ^8.1 v3.0.4PHP ^7.1|^8.0 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/3382770?v=4)[Lucian Gabriel Popescu](/maintainers/aherne)[@aherne](https://github.com/aherne) --- Top Contributors [![aherne](https://avatars.githubusercontent.com/u/3382770?v=4)](https://github.com/aherne "aherne (32 commits)")[![luciangreentree](https://avatars.githubusercontent.com/u/20677068?v=4)](https://github.com/luciangreentree "luciangreentree (1 commits)") --- Tags localizationinternationalizationi18n ### Embed Badge ![Health badge](/badges/lucinda-internationalization/health.svg) ``` [![Health](https://phpackages.com/badges/lucinda-internationalization/health.svg)](https://phpackages.com/packages/lucinda-internationalization) ``` ### Alternatives [symfony/intl Provides access to the localization data of the ICU library 2.6k213.6M1.4k](/packages/symfony-intl)[gettext/languages gettext languages with plural rules 7832.7M12](/packages/gettext-languages)[aplus/language Aplus Framework Language Library 2391.7M15](/packages/aplus-language)[aura/intl The Aura Intl package provides internationalization tools, specifically message translation. 938.5M4](/packages/aura-intl)[punic/punic PHP-Unicode CLDR 1573.0M31](/packages/punic-punic)[tractorcow/silverstripe-fluent Simple localisation for Silverstripe 91437.9k29](/packages/tractorcow-silverstripe-fluent) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)