PHPackages tangramor/php-i18n - 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. tangramor/php-i18n ActiveLibrary[Localization & i18n](/categories/localization) tangramor/php-i18n ================== Simple i18n class for PHP 313[1 issues](https://github.com/tangramor/php-i18n/issues)PHP Since Jul 26Pushed 1y ago1 watchersCompare [ Source](https://github.com/tangramor/php-i18n)[ Packagist](https://packagist.org/packages/tangramor/php-i18n)[ RSS](/packages/tangramor-php-i18n/feed)WikiDiscussions master Synced today READMEChangelogDependenciesVersions (1)Used By (0) [中文](README.zh-CN.md) --------------------- [](#中文) PHP i18n Library ================ [](#php-i18n-library) A simple and efficient internationalization (i18n) library for PHP that allows you to manage multiple languages in your application. This project is inspired by the **[i18n library](https://github.com/Philipp15b/php-i18n)** by **Philipp Schröer**. The original library cannot switch languages dynamically during runtime, which is a limitation. This fork aims to address this issue and provide a more flexible solution. If you don't need the dynamic language switching feature, you can still use the original **[i18n library](https://github.com/Philipp15b/php-i18n)** by **Philipp Schröer**. Features -------- [](#features) - Supports language variants like "en-US", "zh-CN", etc. - Automatic detection of user's language preference. - Fallback language support to ensure all strings have a default translation. - Caching mechanism to improve performance. - Change language dynamically during runtime. Installation ------------ [](#installation) You can install the library via [Composer](https://getcomposer.org/): ``` composer require tangramor/php-i18n ``` Or you can download the `i18n.php` file and include it in your project. How to use this lib ------------------- [](#how-to-use-this-lib) ### Configuration [](#configuration) Language files should be placed in the specified `filePath` directory and follow the naming convention `{LANGUAGE}.ini`. For example, `en-US.ini` for American English. This fork disabled YAML format and only support **INI** format. Because to support YAML, we need to add a dependency "mustangostang/spyc" for YAML, which is not necessary for this project. #### Language File Example (`en-US.ini`) [](#language-file-example-en-usini) ``` greeting = "Hello, World!" [category] somethingother = "Something other..." ``` #### Settings [](#settings) - Language file path (default: `./lang/{LANGUAGE}.ini`) - Cache file path (default: `./langcache/`) - Preserve language region variants: if set to true, region variants in language code strings such as en-US and en-GB will be preserved, otherwise will be trimmed to en (default: `true`, **NOTE** in the original i18n lib this value is default *false* ) - The fallback language, if no one of the user languages is available (default: `en-US`, **NOTE** in the original i18n lib this value is default *en* ) - A forced language, if you want to force a language (default: `none`) - The section separator: this is used to seperate the sections in the language class. If you set the separator to \_abc\_ you could access your localized strings via `$L->t('category_abc_stringname')` if you use categories in your ini. (default: `_`) - Merge keys from the fallback language into the current language. (default: `false`) ### Useage [](#useage) 1. **Initialization**: Create an instance of the `i18n` class and initialize it with your desired settings. ``` $i18n = new i18n(); $i18n->init(); //use default settings ``` 2. **Set Language Preferences**: Optionally, you can set a forced language or a fallback language. ``` $i18n->setForcedLang('zh-CN'); // or $i18n->setFallbackLang('en-US'); $i18n->init(); ``` 3. **Other Settings**: You can also set other settings like the file path, cache path, etc. ``` $i18n->setCachePath('/tmp/langcache'); //Cache file path (default: ./langcache/) $i18n->setFilePath('/app/lang/{LANGUAGE}.ini'); // language file path (default: ./lang/{LANGUAGE}.ini) $i18n->setMergeFallback(false); // make keys available from the fallback language (default: false) $i18n->setLangVariantEnabled(false); //Allow region variants such as "en-us", "en-gb" etc. If set to false, "en" will be provided. (default: true) $i18n->setSectionSeparator('_'); //this is used to seperate the sections in the language class (default: _) $i18n->init(); ``` 4. **Translate**: Use the `translate` method of `LangManager` class to get the translated string. ``` $L = LangManager::getInstance($i18n->getAppliedLang()); echo $L->translate('greeting'); //or use short form echo $L->t('greeting'); // Output: Hello, World! echo $L->t('category_somethingother'); // Output: Something other... ``` You can change the translation language dynamically during runtime by calling `LangManager::getInstance($otherLang)`. Check the [test code](./test/tests/DefaultSettingTest.php) for examples: ``` $L1 = LangManager::getInstance('en-US'); $this->assertEquals("Hello, World!", $L1->t('greeting')); $L2 = LangManager::getInstance('zh-CN'); $this->assertEquals("世界，你好！", $L2->t('greeting')); ``` Caching ------- [](#caching) The library uses a caching mechanism to store compiled language files. Ensure the `cachePath` directory is writable. How the user language detection works ------------------------------------- [](#how-the-user-language-detection-works) This class tries to detect the user's language by trying the following sources in this order: 1. Forced language (if set) 2. HTTP header 'CURRENT\_LANGUAGE' 3. GET parameter 'lang' (`$_GET['lang']`) 4. SESSION parameter 'lang' (`$_SESSION['lang']`) 5. HTTP\_ACCEPT\_LANGUAGE (can be multiple languages) (`$_SERVER['HTTP_ACCEPT_LANGUAGE']`) 6. COOKIE stored variable 'lang' (`$_COOKIE['lang']`) 7. Fallback language php-i18n will remove all characters that are not one of the following: A-Z, a-z or 0-9 to prevent [arbitrary file inclusion](https://en.wikipedia.org/wiki/File_inclusion_vulnerability). After that the class searches for the language files. For example, if you set the GET parameter 'lang' to 'en-US' without a forced language set, the class would try to find the file `lang/en-US.ini` (if the setting `langFilePath` was set to default (`lang/{LANGUAGE}.ini`)). If this file doesn't exist, php-i18n will try to find the language file for the language defined in the session variable and so on. ### Example for 'CURRENT\_LANGUAGE' in javascript [](#example-for-current_language-in-javascript) You can set the 'CURRENT\_LANGUAGE' header in your axios request to pass the language to the server. Following example intercepts the axios request to add the 'CURRENT\_LANGUAGE' header, you can change it to your own way. ``` import axios from 'axios'; import i18n from './i18n'; axios.interceptors.request.use(function (config) { config.headers['CURRENT_LANGUAGE'] = i18n.locale; return config }, function (error) { return Promise.reject(error); }); ``` ### How to change this implementation [](#how-to-change-this-implementation) You can change the user detection by extending the i18n class and overriding the getUserLangs() method: ``` ``` This very basic extension only uses the GET parameter 'language' and the session parameter 'userlanguage'. You see that this method must return an array. Test ---- [](#test) To run the tests, you need to install the `phpunit/phpunit` package under `test` folder. ``` cd test composer install # or composer require --dev phpunit/phpunit ``` Then run the tests with the following command under `test` folder: ``` ./vendor/bin/phpunit --testdox tests ``` License ------- [](#license) This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. Contributing ------------ [](#contributing) Contributions are welcome! Please feel free to fork the project and submit pull requests. Contact ------- [](#contact) For any questions or issues, please open an issue or contact the author directly. ### Health Score 14 — LowBetter than 1% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity9 Limited adoption so far Community7 Small or concentrated contributor base Maturity18 Early-stage or recently created project Bus Factor1 Top contributor holds 100% 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. ### Community Maintainers ![](https://avatars.githubusercontent.com/u/491287?v=4)[tangramor](/maintainers/tangramor)[@tangramor](https://github.com/tangramor) --- Top Contributors [![tangramor](https://avatars.githubusercontent.com/u/491287?v=4)](https://github.com/tangramor "tangramor (7 commits)") ### Embed Badge ![Health badge](/badges/tangramor-php-i18n/health.svg) ``` [![Health](https://phpackages.com/badges/tangramor-php-i18n/health.svg)](https://phpackages.com/packages/tangramor-php-i18n) ``` ### Alternatives [smmoosavi/php-gettext Wrapper for php-gettext by danilo segan. This library provides PHP functions to read MO files even when gettext is not compiled in or when appropriate locale is not present on the system. 1927.0k1](/packages/smmoosavi-php-gettext) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)