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 2y 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 2w ago

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

13

—

LowBetter than 1% of packages

Maintenance13

Infrequent updates — may be unmaintained

Popularity9

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity19

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

[smarty-gettext/smarty-gettext

Gettext plugin enabling internationalization in Smarty Package files

752.5M8](/packages/smarty-gettext-smarty-gettext)[devaslanphp/auto-translate

Auto generate translation JSON files

6627.3k](/packages/devaslanphp-auto-translate)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)