包简介

High-performance API performing internationalization and localization for PHP applications via JSON files

README 文档

README

Table of contents:

About
- How Are Locales Detected
- How Are Translations Stored
Configuration
Execution
Installation
Unit Tests
Reference Guide

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

This way your HTML view becomes a web of units expected to be translated on compilation, as in example below:

<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:

configuration: setting up an XML file where API is configured for locale detection and translations storage
execution: creating a Lucinda\Internationalization\Wrapper 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: describes how to install API on your computer, in light of steps above
unit tests: API has 100% Unit Test coverage, using UnitTest API instead of PHPUnit for greater flexibility
example: shows a deep example of API functionality based on unit test for Lucinda\Internationalization\Wrapper

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:

{"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:

<internationalization method="..." folder="..." locale="..." domain="..." extension="..."/>

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:

$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:

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:

getReader: gets a Lucinda\Internationalization\Reader object able to retrieve translations from storage based on detected locale
getWriter: gets a Lucinda\Internationalization\Writer object able to save/delete translations from storage based on detected locale using

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 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:

<html>
	<body>
		<h1>__("title")</h2>
		<p>__("description")</p>
	</body>
</html>

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

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:

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:

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.

lucinda/internationalization 适用场景与选型建议

lucinda/internationalization 是一款基于 PHP 开发的 Composer 扩展包，目前已累计 23.62k 次下载、GitHub Stars 达 0，最近一次更新时间为 2018 年 02 月 12 日，在 PHP 生态内属于活跃度较高的组件。

它主要适用于以下技术方向：「i18n」「localization」「internationalization」等业务场景。在实际项目中，围绕这些方向常见需要落地的问题包括：接口对接、性能调优、并发安全、与既有框架（Laravel / ThinkPHP / Yii / Webman 等）的兼容适配，以及生产环境的日志埋点与稳定性保障。

我们在过去多个企业项目中使用过 lucinda/internationalization 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 lucinda/internationalization 我们能提供哪些服务？

定制开发 / 二次开发

基于 lucinda/internationalization 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发

与 lucinda/internationalization 相关的其它包

同方向 / 同关键字的高下载量 PHP Composer 包推荐，方便对比选型：

delfimov/translate 16

Easy to use i18n translation PHP class for multi-language websites

awes-io/localization-helper 35

Package for convenient work with Laravel's localization features

atk14/localized-decimal-field 0

Field for number with restricted count of digits and decimal places

geertw/yii2-translatable-url-rule 14

A custom URL rule class for Yii 2 which allows to create translated URL rules

marvinrabe/laravel-intl 5

Easy to use internationalization functions for Laravel

tariq86/country-list 7

List of all countries with names and ISO 3166-1 codes in all languages and data formats for Laravel

lucinda/internationalization

包简介

关键字：