README

A micro multi-language (i18n) translation library for PHP. Load language packs from plain PHP files, look up keys (including dot-delimited nested keys), interpolate {name} placeholders, and fall back to a default language when a translation is missing.

Features

• Two on-disk layouts: one file per language, or one directory per language.
• Nested keys via dot notation (admin.dashboard, errors.http.404).
• Placeholder interpolation (Welcome {user}) from a context map.
• Fallback chain: active language → inline fallback → default language → the key itself.
• No runtime dependencies. Loaded languages are cached in memory.

Requirements

• PHP 8.1 or higher

Installation

composer require initphp/translator

Quick start

require_once 'vendor/autoload.php';

use InitPHP\Translator\Translator;

$lang = new Translator();
$lang->setDir(__DIR__ . '/languages/')
    ->setDefault('en');

$lang->change('tr'); // switch the active language

echo $lang->translate('hello');

A language file simply returns an array:

<?php
// languages/en.php
return [
    'hello'   => 'Hello {user}',
    'today'   => "It's {day}",
];

echo $lang->translate('hello', null, ['user' => 'Ada']); // "Hello Ada"

File layout vs. directory layout

Choose how your language packs are stored. Pick the mode before loading a language (i.e. before setDefault() / change()); the default is file mode.

File mode — one file per language

languages/
    en.php
    tr.php
    fr.php

$lang = new Translator();
$lang->useFile() // optional; this is the default
    ->setDir(__DIR__ . '/languages/')
    ->setDefault('en');

echo $lang->translate('hello');

Directory mode — one directory per language

Each *.php file becomes a namespace keyed by its (lower-cased) file name, and keys are addressed as filename.key:

languages/
    en/
        user.php
        admin.php
    tr/
        user.php
        admin.php

$lang = new Translator();
$lang->useDirectory() // note: call before setDefault()/change()
    ->setDir(__DIR__ . '/languages/')
    ->setDefault('en');

echo $lang->translate('user.hello');   // user.php => ['hello' => '...']
echo $lang->translate('admin.dashboard');

How a key is resolved

translate() resolves a key in this order and returns the first hit:

1. The active language (set by setDefault() or change()).
2. The inline fallback string, if you passed one (it is interpolated too).
3. The default language, when it differs from the active one.
4. The key itself, returned verbatim, if nothing matched.

$lang->setDefault('en')->change('tr');

$lang->translate('errors.e404');                 // tr → (missing) → en → "Not Found"
$lang->translate('greeting', 'Hi {user}', [      // tr missing → inline fallback
    'user' => 'Ada',
]);                                              // "Hi Ada"
$lang->translate('unknown.key');                 // nowhere → "unknown.key"

Note: a key that points to a nested array (a namespace) rather than a string is treated as a miss and falls through the chain — it never throws.

Placeholders

Markers are written {name} and replaced from the context map. Scalar values and objects implementing __toString() are stringified; arrays and other objects are ignored, and unmatched markers are left untouched.

$lang->translate('errorMsg', null, ['code' => 2005]);
// "Something went wrong. Code : 2005"

Methods

All configuration methods return $this, so calls can be chained.

Documentation

Full guides with examples live in docs/:

• Getting started
• File mode · Directory mode
• Key resolution & fallback
• Placeholders
• API reference
• Exceptions

Getting help

If you have questions, bug reports, or feature requests, please open an issue in the issue tracker.

Contributing

All contributions to this project will be published under the MIT License. By submitting a pull request or filing a bug, issue, or feature request, you are agreeing to comply with this waiver of copyright interest.

Before opening a pull request, run the full local check bundle:

composer ci   # cs-check + stan + test

• Fork it ( https://github.com/InitPHP/Translator/fork )
• Create your feature branch (git checkout -b feat/my-feature)
• Commit your changes (git commit -am 'Add some feature')
• Push to the branch (git push origin feat/my-feature)
• Create a new Pull Request

Credits

• Muhammet ŞAFAK <info@muhammetsafak.com.tr>

License

Copyright © 2022 InitPHP — released under the MIT License.