PHPackages                             danil-kashin/localization - 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. danil-kashin/localization

ActiveLibrary[Localization & i18n](/categories/localization)

danil-kashin/localization
=========================

A PHP localization package for managing translations

v1.0.0(3mo ago)045↓90.9%BSD-3-ClausePHPPHP >=8.5

Since Apr 1Pushed 3mo agoCompare

[ Source](https://github.com/KashinDanil/Localization)[ Packagist](https://packagist.org/packages/danil-kashin/localization)[ RSS](/packages/danil-kashin-localization/feed)WikiDiscussions main Synced 4w ago

READMEChangelogDependencies (1)Versions (2)Used By (0)

Localization
============

[](#localization)

A lightweight PHP localization package for managing translations. Instantiate a `Translator` with a language and a path to your JSON translation files, and wire it up however your application requires.

Requirements
------------

[](#requirements)

- PHP 8.5+

Installation
------------

[](#installation)

```
composer require danil-kashin/localization
```

Quick start
-----------

[](#quick-start)

Create a JSON translation file for each language you support:

```
translations/
    ru.json
    de.json

```

```
{
    "Hello": "Привет",
    "Goodbye": "До свидания"
}
```

Instantiate a `Translator` and call `translate()`:

```
use DanilKashin\Localization\Translator;
use DanilKashin\Localization\Language;

$translator = new Translator(
    language: 'ru',
    translationsPath: __DIR__ . '/translations',
);

echo $translator->translate('Hello');   // Привет
echo $translator->translate('Goodbye'); // До свидания
echo $translator->translate('Missing'); // Missing  (falls back to original text)
```

Translations are loaded lazily on the first call to `translate()`.

Languages
---------

[](#languages)

The `Language` class contains constants for all 184 ISO 639-1 language codes:

```
use DanilKashin\Localization\Language;

new Translator(Language::RU, __DIR__ . '/translations');
new Translator(Language::DE, __DIR__ . '/translations');
new Translator(Language::ZH, __DIR__ . '/translations');
```

The default language is `Language::EN`. If you need codes beyond ISO 639-1, extend the class:

```
class MyLanguage extends Language
{
    const string ZH_TW = 'zh-TW'; // Traditional Chinese
}
```

### Normalizing language codes

[](#normalizing-language-codes)

`Language::fromCode()` normalizes arbitrary codes (e.g. from `Accept-Language` headers or Telegram's `language_code`) to a 2-character lowercase string:

```
Language::fromCode('en-US'); // 'en'
Language::fromCode('RU');    // 'ru'
```

Default language
----------------

[](#default-language)

The default language is `Language::EN` (`'en'`). Translating in the default language always returns the original text unchanged — no file is loaded and no missing-key tracking occurs.

You can change the default:

```
$translator = new Translator(
    language: 'de',
    translationsPath: __DIR__ . '/translations',
    defaultLanguage: 'de',
);

$translator->isDefaultLanguage(); // true
$translator->translate('Hello');  // 'Hello' (no translation attempted)
```

Tracking missing translations
-----------------------------

[](#tracking-missing-translations)

Pass a `MissingTranslationHandlerInterface` to be notified whenever a key has no translation. The built-in `JsonFileMissingTranslationHandler` appends missing keys to a JSON file:

```
use DanilKashin\Localization\JsonFileMissingTranslationHandler;

$handler = new JsonFileMissingTranslationHandler(__DIR__ . '/missing.json');

$translator = new Translator(
    language: 'ru',
    translationsPath: __DIR__ . '/translations',
    missingHandler: $handler,
);

$translator->translate('An untranslated string');
// missing.json → { "ru": ["An untranslated string"] }
```

The file is created if it does not exist. Duplicate keys are never written twice.

### Custom handler

[](#custom-handler)

Implement the interface to handle missing keys your own way (logging, alerting, etc.):

```
use DanilKashin\Localization\MissingTranslationHandlerInterface;

class LoggingHandler implements MissingTranslationHandlerInterface
{
    public function handle(string $language, string $text): void
    {
        // log or alert
    }
}
```

Dependency injection
--------------------

[](#dependency-injection)

`Translator` implements `TranslatorInterface`, so you can type-hint against the interface in your own code:

```
use DanilKashin\Localization\TranslatorInterface;

class MyService
{
    public function __construct(private readonly TranslatorInterface $translator) {}
}
```

License
-------

[](#license)

BSD-3-Clause. See [LICENSE](LICENSE).

###  Health Score

40

—

FairBetter than 86% of packages

Maintenance82

Actively maintained with recent releases

Popularity10

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity51

Maturing project, gaining track record

 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.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

90d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/808cc658e54eb99caa9573723ab97993e9fcd90d2b6cd0940a1ba7eb8950f8cf?d=identicon)[KashinDanil](/maintainers/KashinDanil)

---

Top Contributors

[![KashinDanil](https://avatars.githubusercontent.com/u/51259240?v=4)](https://github.com/KashinDanil "KashinDanil (1 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/danil-kashin-localization/health.svg)

```
[![Health](https://phpackages.com/badges/danil-kashin-localization/health.svg)](https://phpackages.com/packages/danil-kashin-localization)
```

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

1926.6k1](/packages/smmoosavi-php-gettext)[laradevs/spanish

labels translated to spanish

166.7k](/packages/laradevs-spanish)

PHPackages © 2026

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