Home

InitPHP Translator — Wiki

Welcome to the official documentation for initphp/translator — a micro multi-language (i18n) translation library for PHP. You keep your translations in plain PHP files, point the translator at a directory, and read keys with one call. It supports nested keys, {name} placeholder interpolation, and an automatic fallback to a default language when a translation is missing.

No runtime dependencies. Loaded languages are cached in memory for the lifetime of the instance.

The package ships two public types:

Type	Purpose
Translator	The default concrete implementation (final).
TranslatorInterface	The contract — type-hint this in your services.
TranslatorException	Thrown on misconfiguration (bad path, missing/invalid pack, wrong call order).

composer require initphp/translator

use InitPHP\Translator\Translator;

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

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

echo $lang->translate('welcome', null, ['user' => 'Ada']);

A language file is just a PHP file that returns an array:

<?php
// languages/tr.php
return [
    'welcome' => 'Hoşgeldin {user}',
];

Start here

• New to the package? Read Installation, then Quick Start.
• One file or one directory per language? Compare File Mode and Directory Mode.
• How is a key resolved, and when does fallback kick in? Read Keys & Fallback.
• Templating values into messages? Read Placeholders.
• Looking for a specific method? The full API Reference lists every public member.
• Handling errors? Read Exceptions.
• Practical patterns? See Recipes and Testing.
• Upgrading from 0.2? Read Migration (0.x → 1.0).

At a glance — capabilities

Capability	Supported
One file per language (en.php)	✅
One directory per language (en/admin.php → admin.*)	✅
Dot-delimited nested keys (errors.http.404)	✅
{name} placeholder interpolation	✅
Scalar & Stringable placeholder values	✅
Inline per-call fallback text	✅
Automatic fallback to the default language	✅
In-memory caching of loaded languages	✅
Graceful misses (missing key returns the key, never throws)	✅
Plural rules / gender / ICU MessageFormat	❌ (not in scope — see FAQ)

The resolution model in one line

translate() returns the first of: the active language → the inline fallback you passed → the default language → the key itself. See Keys & Fallback for the full picture.

Package metadata

• License: MIT
• Minimum PHP: 8.1 (tested on 8.1 – 8.4)
• Runtime dependencies: none
• Packagist: initphp/translator
• Source: github.com/InitPHP/Translator
• Issues: github.com/InitPHP/Translator/issues
• Discussions: github.com/orgs/InitPHP/discussions
• Security: SECURITY.md

If something in this wiki is unclear, ambiguous, or wrong, please open an issue — documentation fixes are reviewed eagerly.