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.
- 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.
- PHP 8.2 or higher
composer require initphp/translatorrequire_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"Choose how your language packs are stored. Pick the mode before loading a
language (i.e. before setDefault() / change()); the default is file mode.
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');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');translate() resolves a key in this order and returns the first hit:
- The active language (set by
setDefault()orchange()). - The inline fallback string, if you passed one (it is interpolated too).
- The default language, when it differs from the active one.
- 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.
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"| Method | Description |
|---|---|
setDir(string $dir): self |
Sets the base directory of the language packs. Trailing slashes are trimmed. Throws if the path is not a directory. |
useFile(): self |
Selects file mode (default). Call before loading a language. |
useDirectory(): self |
Selects directory mode. Call before loading a language. |
setDefault(string $default): self |
Sets and loads the default (fallback) language; becomes the active one if none is set. |
change(string $current): self |
Switches the active language, loading it on first use. |
translate(string $key, ?string $fallback = null, array $context = []): string |
Returns the resolved, interpolated translation. |
render(string $key, ?string $fallback = null, array $context = []): void |
Echoes the value of translate(). |
_r(...) |
Deprecated alias of translate(), kept for backward compatibility. |
_e(...) |
Deprecated alias of render(), kept for backward compatibility. |
All configuration methods return $this, so calls can be chained.
Full guides with examples live in docs/:
If you have questions, bug reports, or feature requests, please open an issue in the issue tracker.
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
Copyright © 2022 InitPHP — released under the MIT License.