Internationalization library for PHP.
- Translations based on
JSON
,YAML
files; - Easy addition of new sources files;
- Interpolated translations;
- Pluralization;
composer require chipslays/phrase
Locale file: locales/yaml/en_US.yml
# interpolated message
hello: Hello {name}!
# pluralization
plural: I have {count} {{eng:{count},melon}} and {money} {{eng:{money},dollar}}.
# message can be a array
array:
text: This is my flag.
image: images/en-flag.jpg
myKey: myValue
Locale file: locales/json/en_US.json
{
"hello": "Hello {name}!",
"plural": "I have {count} {{eng:{count},melon}} and {money} {{eng:{money},dollar}}.",
"array": {
"text": "This is my flag.",
"image": "images/en-flag.jpg"
}
}
// Engine constructor
__construct(string $root, string $locale, ?string $fallback);
use Chipslays\Phrase\Phrase;
use Chipslays\Phrase\Engine\JsonEngine;
$engine = new JsonEngine(__DIR__ . '/locales/json', 'en_US');
$phrase = new Phrase($engine);
$phrase->get(...);
use Chipslays\Phrase\Phrase;
use Chipslays\Phrase\Engine\YamlEngine;
$engine = new YamlEngine(__DIR__ . '/locales/yaml', 'en_US');
$phrase = new Phrase($engine);
$phrase->get(...);
use Chipslays\Phrase\Phrase;
use Chipslays\Phrase\Engine\JsonEngine;
$engine = new JsonEngine(__DIR__ . '/locales/json', 'en_US');
Phrase::setEngine($engine);
Phrase::get(...);
$phrase->get(string $key, ?array $replace = null, ?string $locale = null);
# key - locale message key
# replace - array with interpolation
# locale - force locale (useful when using multiple locales at the same time)
$phrase->get('hello');
Phrase::get('hello');
__('hello');
Pass language code for force use.
$phrase->get('hello', null, 'ru_RU');
Phrase::get('hello', null, 'ru_RU');
__('hello', null, 'ru_RU');
Pass named arguments to interpolate your translations.
$phrase->get('hello', ['{name}' => 'John Doe']);
Phrase::get('hello', ['{name}' => 'John Doe']);
__('hello', ['{name}' => 'John Doe']);
// Hello John Doe!
English pluralization phrase:
{{eng:{count},melon}}
Russian pluralization phrase:
{{rus:{count},арбуз,арбуза,арбузов}}
# english locale file
# for english plural word have 1 form
...
plural: I have {count} {{eng:{count},melon}} and {money} {{eng:{money},dollar}}.
....
# russian locale file
# for russian plural word have 3 forms
...
plural: У меня есть {count} {{rus:{count},арбуз,арбуза,арбузов}} и {money} {{rus:{money},рубль,рубля,рублей}}
....
$phrase->get('plural', ['{count}' => 1, '{money}' => 100])
Phrase::get('plural', ['{count}' => 1, '{money}' => 100])
__('plural', ['{count}' => 1, '{money}' => 100])
// I have 1 melon and 100 dollars.
Use patch
method if you need to add messages to an already loaded file.
If this locale was not previously loaded, it will simply be loaded.
Use load
method for delete and overwrite all previous messages by locale.
use Chipslays\Phrase\Phrase;
use Chipslays\Phrase\Engine\YamlEngine;
$engine = new YamlEngine(__DIR__ . '/locales/yaml', 'en_US');
$phrase = new Phrase($engine);
// this method loaded en_US.yml file from MyPlugin dir and merge with previously loaded locale en_US
$phrase->patch(__DIR__ . '/locales/plugins/MyPlugin/', 'en_US');
// this method delete and overwrite all previous messages
$phrase->load(__DIR__ . '/locales/yaml', 'en_US');
use Chipslays\Phrase\Plural;
echo Plural::eng(10, 'melon'); // melons
echo Plural::rus(10, ['арбуз', 'арбуза', 'арбузов']); // арбузов
__(string $key, ?array $replace = null, ?string $locale = null): string|array
__('hello', ['{name}' => 'John Doe'], 'en_US');
Example for YamlEngine
:
use Chipslays\Phrase\Engine\AbstractEngine;
use Chipslays\Phrase\Exceptions\PhraseException;
class YamlEngine extends AbstractEngine
{
/**
* @param string $locale
* @return void
*
* @throws PhraseException
*/
protected function load(string $locale): void
{
$path = $this->root . '/' . $locale . '.yml';
if (!file_exists($path)) {
throw new PhraseException("Locale file not found in path {$path}", 1);
}
$this->locales[$locale] = yaml_parse_file($path);
}
}
MIT