https://github.com/chipslays/phrase
🌐 Internationalization library for PHP.
https://github.com/chipslays/phrase
internationalization-library lightweight localization php translation
Last synced: 10 months ago
JSON representation
🌐 Internationalization library for PHP.
- Host: GitHub
- URL: https://github.com/chipslays/phrase
- Owner: chipslays
- License: mit
- Created: 2021-06-16T19:56:43.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2021-09-25T09:20:12.000Z (over 4 years ago)
- Last Synced: 2025-05-31T19:56:01.975Z (about 1 year ago)
- Topics: internationalization-library, lightweight, localization, php, translation
- Language: PHP
- Homepage:
- Size: 31.3 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# 🌐 Phrase
Internationalization library for PHP.
## Features
* Translations based on [`JSON`](examples/locales/json), [`YAML`](examples/locales/yaml) files;
* Easy addition of new [sources files](src/Engine);
* Interpolated translations;
* Pluralization;
## Installation
```bash
composer require chipslays/phrase
```
## Setup
Locale file: `locales/yaml/en_US.yml`
```yaml
# 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`
```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
```php
// Engine constructor
__construct(string $root, string $locale, ?string $fallback);
```
```php
use Chipslays\Phrase\Phrase;
use Chipslays\Phrase\Engine\JsonEngine;
$engine = new JsonEngine(__DIR__ . '/locales/json', 'en_US');
$phrase = new Phrase($engine);
$phrase->get(...);
```
```php
use Chipslays\Phrase\Phrase;
use Chipslays\Phrase\Engine\YamlEngine;
$engine = new YamlEngine(__DIR__ . '/locales/yaml', 'en_US');
$phrase = new Phrase($engine);
$phrase->get(...);
```
```php
use Chipslays\Phrase\Phrase;
use Chipslays\Phrase\Engine\JsonEngine;
$engine = new JsonEngine(__DIR__ . '/locales/json', 'en_US');
Phrase::setEngine($engine);
Phrase::get(...);
```
### Get message
```php
$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)
```
```php
$phrase->get('hello');
Phrase::get('hello');
__('hello');
```
Pass language code for force use.
```php
$phrase->get('hello', null, 'ru_RU');
Phrase::get('hello', null, 'ru_RU');
__('hello', null, 'ru_RU');
```
### Interpolation
Pass named arguments to interpolate your translations.
```php
$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},арбуз,арбуза,арбузов}}
```
```yaml
# english locale file
# for english plural word have 1 form
...
plural: I have {count} {{eng:{count},melon}} and {money} {{eng:{money},dollar}}.
....
```
```yaml
# russian locale file
# for russian plural word have 3 forms
...
plural: У меня есть {count} {{rus:{count},арбуз,арбуза,арбузов}} и {money} {{rus:{money},рубль,рубля,рублей}}
....
```
```php
$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.
```php
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');
```
```php
use Chipslays\Phrase\Plural;
echo Plural::eng(10, 'melon'); // melons
echo Plural::rus(10, ['арбуз', 'арбуза', 'арбузов']); // арбузов
```
### Helpers
```php
__(string $key, ?array $replace = null, ?string $locale = null): string|array
```
```php
__('hello', ['{name}' => 'John Doe'], 'en_US');
```
### Custom locale file (Engine)
Example for `YamlEngine`:
```php
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