chipslays/phrase

Internationalization library for PHP.

1.0.2 2021-08-30 20:20 UTC

Requires (Dev)

• phpunit/phpunit: ^9.5

MIT

README

Internationalization library for PHP.

Features

• Translations based on JSON, YAML files;
• Easy addition of new sources files;
• Interpolated translations;
• Pluralization;

Installation

composer require chipslays/phrase

Setup

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"
    }
}

Usage

Create Phrase instance

// 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(...);

Get message

$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');

Interpolation

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!

Pluralization

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.

Merge locale messages (load, patch)

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, ['арбуз', 'арбуза', 'арбузов']); // арбузов

Helpers

__(string $key, ?array $replace = null, ?string $locale = null): string|array

__('hello', ['{name}' => 'John Doe'], 'en_US');

Custom locale file (Engine)

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);
    }
}

License

MIT