A file based translation component without dependencies.
It supports every file format you throw at it, pluralization, placeholders, is fully tested and documented.
To install the package with Composer, simply run the following command:
$ composer require michaelspiss/translation
Instantiating a new Translator is easy: Simply pass it the default locale ('en' in this case) and the path to your translations directory!
require 'vendor/autoload.php'; // composer autoloader
use MichaelSpiss\Translation\Translator;
$translator = new Translator('en', 'path/to/translations');The component uses keys in the dot-notation to identify which string to load. To get a string in a specific language use the trans() method and pass it the key:
$translator->trans('message.hello_world');In this case the string would be found in path/to/translations/en/message.php.
The file itself would look like "message.php" below.
Language strings are stored in files in the directory you passed the Translator during initialization. Within this directory each subfolder represents a supported language and holds the translation files.
translations/
|- en/
| |- message.php
|- de/
|- fr/
A translation file would simply look like the following:
<?php
return [
'hello_world' => 'Hello World!'
];Even though only .php files are supported out-of-the-box, translation files can be of every format. For more information, please see the corresponding wiki article.
Normally, the locale is only set once, at the initialization. But the component also allows you to change the locale mid-way, of course:
$translator->setLocale('de');Additionally you can request single translation strings in a specific language without setting a new locale and resetting it afterwards:
$translator->trans('message.hello_world', [], 'de');
// or:
$translator->transChoice('message.choice', 1, [], 'de');In your translation files, a placeholder is defined by putting curly braces around the placeholder name (upper- and lowercase letters only):
<?php
return [
'with_placeholder' => 'Hello {placeholder}!'
];Now you can add an array to your trans() call containing values for the placeholders:
$translator->trans('message.with_placeholder', ['placeholder' => 'World']);
// returns "Hello World!"You can have as many placeholders in a string as you like!
To enable pluralization for a string simply add a pipe-character between the singular and plural form in your translation file:
<?php
return [
'simple_pluralization' => 'Dog | Dogs'
];The second option is a bit more advanced and actually allows you to set your own rules:
<?php
return [
'advanced_pluralization' => '{0} None | [1,10] Some | [11,*] Many'
];You can use the following expressions:
| Expression | Meaning |
|---|---|
| {3} | match exactly 3 |
| [1,10] | match everything from 1 to 10, including 1 and 10 |
| [11,*] | match everything from 11 to infinite including 11 |
| ]10,20] | match everything from 10 to 20, excluding 10, including 20 |
| ]10,20[ | match everything from 10 to 20, excluding 10 and 20 |
| [10,20[ | match everything from 10 to 20, including 10, excluding 20 |
Expressions also support integers and floats!
To get the string use the transChoice() method, which takes an additional
number argument (type int or float):
$translator->transChoice('message.simple_pluralization', 4);
// returns "Dogs"
$translator->transChoice('message.advanced_pluralization', 8);
// returns "Some"If you want further information on the Translator's methods
or how to use other file formats than .php
check out this project's wiki!
- PHP >= 7.0.0
MIT