https://github.com/someson/phalcon-i18n
Extended translation module
https://github.com/someson/phalcon-i18n
i18n internationalization phalcon phalcon3 phalcon4 phalcon5 php translations
Last synced: 5 months ago
JSON representation
Extended translation module
- Host: GitHub
- URL: https://github.com/someson/phalcon-i18n
- Owner: someson
- License: mit
- Created: 2021-05-23T18:05:32.000Z (about 5 years ago)
- Default Branch: 5.0
- Last Pushed: 2024-10-29T18:14:27.000Z (over 1 year ago)
- Last Synced: 2025-10-28T17:30:31.384Z (8 months ago)
- Topics: i18n, internationalization, phalcon, phalcon3, phalcon4, phalcon5, php, translations
- Language: PHP
- Homepage:
- Size: 59.6 KB
- Stars: 5
- Watchers: 2
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Multi-lingual Support
[](https://circleci.com/gh/someson/phalcon-i18n/tree/circleci-project-setup)
[](https://codecov.io/gh/someson/phalcon-i18n)
[](https://supportukrainenow.org/)
[](https://stand-with-ukraine.pp.ua)
Extending [Phalcon Framework v5 Translations Module](https://docs.phalcon.io/5.0/en/translate)
## Install
```bash
$ composer require someson/phalcon-i18n
```
## Example
e.g. `login.json` File:
```json
{
"form": {
"label": {
"identity": "Benutzername",
"password": "Passwort",
"rememberMe": "Ich möchte angemeldet bleiben"
},
"placeholder": {
"identity": "Bitte geben Sie ihren Benutzernamen ein",
"password": "Bitte geben Sie ihr Passwort ein"
},
"button": "Anmelden"
},
"title": {
"h1": "Main Title",
"h2": "some subtitle"
}
}
```
translating path like `login:form.label.identity` returns `Benutzername`
which start with `login:` means file name and the rest of it is a pure json path.
## Usage
### 1. Simple usage
```php
// component using a singleton pattern, so we can instantiate it before the framework itself
// or wrap it into some global function
$t = \Phalcon\I18n\Translator::instance();
// using the "de" directory, "en" by default
$t->setLang('de');
// equal to "global:a", hence "global" is a default scope
echo $t->_('a');
// placeholder "key" replaced through "value"
echo $t->_('b', ['key' => 'value']);
// nested key
echo $t->_('c.d.e', ['key' => 'value']);
// nested key from the "api" scope (filename === scope, if files used)
echo $t->_('api:c.d.e', ['key' => 'value']);
```
### 2. Advanced usage
in any bootstrap file (i.e. `index.php`) define:
```php
use \Phalcon\I18n\Translator;
if (! function_exists('__')) {
function __(string $key, array $params = [], bool $pluralize = true): string {
return $key ? Translator::instance()->_($key, $params, $pluralize) : '[TRANSLATION ERROR]';
}
}
```
inside your code:
```php
$translation = __('a.b.c');
```
or in any view:
```html
= __('a.b.c') ?>
```
```twig
{{ __('a.b.c') }}
```
## Configure
default config `\Phalcon\I18n\Config\Default.php`:
```php
return [
'defaultLang' => 'en',
'defaultScope' => 'global',
// loads data from chosen source (e.g. Json) by chosen loader (e.g. Files)
// can be e.g. "Mysql" by "Database" (feel free to implement)
'loader' => [
'className' => \Phalcon\I18n\Loader\Files::class,
'arguments' => ['path' => $_SERVER['DOCUMENT_ROOT'] . DIRECTORY_SEPARATOR . 'locale'],
],
// reads the source and translates it into chosen type of handler (@see key "handler")
'adapter' => [
'className' => \Phalcon\I18n\Adapter\Json::class,
],
// implements \Phalcon\Translate\AdapterInterface
// returns an object of all translations of the specific language
// provides functionality for placeholder replacing
'handler' => [
'options' => [
'flatten' => ['shift' => 1],
],
],
// replaces user-defined (or '%' by default) placeholders
'interpolator' => [
'className' => \Phalcon\I18n\Interpolator\AssocArray::class,
'arguments' => ['{{', '}}'],
],
// bool only
'collectMissingTranslations' => true,
// - false
// - sprintf pattern e.g. [# %s #]
// - \Phalcon\I18n\Interfaces\DecoratorInterface object
'decorateMissingTranslations' => new \Phalcon\I18n\Decorator\HtmlCode,
];
```
you may want to override it with your own config (by default used in `config` container having `i18n` scope):
```php
return [
// ...
'i18n' => [
'loader' => [
'arguments' => ['path' => '/my/own/path/to/locale/'],
],
'interpolator' => [
'arguments' => ['[[', ']]'],
],
'collectMissingTranslations' => false,
'decorateMissingTranslations' => '[# %s #]',
],
// ...
];
```
## Running Tests
[Codeception](https://codeception.com/) used
```
$ docker-compose exec i18n ./vendor/bin/codecept build
```
To run tests, run the following command:
```
$ docker-compose exec i18n ./vendor/bin/codecept run [-vv]
```
For code coverage info run
```
$ docker-compose exec i18n ./vendor/bin/codecept run --coverage --coverage-html
```
and open `tests/_output/coverage/index.html` in your browser
### Static analyzer
`$ docker-compose exec i18n ./vendor/bin/phpstan analyse src --level max`