someson / phalcon-i18n
Multi-lingual support (extended)
v1.3.1
2022-06-01 23:02 UTC
Requires
- php: 8.0.*
- ext-json: *
- ext-phalcon: 5.0.*
Requires (Dev)
- codeception/codeception: ^4.1
- codeception/module-asserts: ^1.3
- codeception/module-phalcon5: ^1.0
- phalcon/ide-stubs: v5.0.0-RC1
- phpstan/phpstan: ^0.12
Suggests
- ext-yaml: Needed to support YAML format as an adapter class
README
Extending Phalcon Framework v5 Translations Module
Example
e.g. login.json
File:
{ "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
// 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:
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:
$translation = __('a.b.c');
or in any view:
<h1><?= __('a.b.c') ?></h1>
<h1>{{ __('a.b.c') }}</h1>
Configure
default config \Phalcon\I18n\Config\Default.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):
return [ // ... 'i18n' => [ 'loader' => [ 'arguments' => ['path' => '/my/own/path/to/locale/'], ], 'interpolator' => [ 'arguments' => ['[[', ']]'], ], 'collectMissingTranslations' => false, 'decorateMissingTranslations' => '[# %s #]', ], // ... ];
Running Tests
Codeception used
To run tests, run the following command:
$ docker-compose exec php-service ./vendor/bin/codecept run unit [-vv]
$ docker-compose exec php-service ./vendor/bin/codecept run --coverage
Codeception PHP Testing Framework v4.1.31 https://helpukrainewin.org
Powered by PHPUnit 9.5.20 #StandWithUkraine
Unit Tests (29) ----------------------------------------------------------
✔ AdapterTest: Json found and initialized (0.23s)
✔ AdapterTest: Json may throw exceptions (0.10s)
✔ ConfigTest: Must be functional with config service (0.11s)
✔ ConfigTest: Must be functionable without config service (0.02s)
✔ ConfigTest: Must be functionable with wrong config (0.01s)
✔ DecoratorTest: No decoration (0.02s)
✔ DecoratorTest: Decorate as text pattern (0.02s)
✔ DecoratorTest: Decorate as html (0.02s)
✔ HandlerTest: Check keys shifting | #0 (0.01s)
✔ HandlerTest: Check keys shifting | #1 (0.01s)
✔ HandlerTest: Check keys shifting | #2 (0.01s)
✔ InterpolatorTest: Should handle default placeholders (0.00s)
✔ InterpolatorTest: Should handle custom placeholders (0.00s)
✔ LoaderTest: Files loader | #0 (0.08s)
✔ LoaderTest: Files loader | #1 (0.02s)
✔ TranslatorTest: Fallback loaded (0.03s)
✔ TranslatorTest: Wrong fallback lang defined (0.01s)
✔ TranslatorTest: Default instance (0.01s)
✔ TranslatorTest: Change language (0.00s)
✔ TranslatorTest: Change scope (0.00s)
✔ TranslatorTest: Changed scope should return a new collection (0.02s)
✔ TranslatorTest: Check if translation exists (0.03s)
✔ TranslatorTest: Plural (0.02s)
✔ TranslatorTest: Context (0.02s)
✔ TranslatorTest: Missing translations (0.02s)
✔ TranslatorTest: Simple translation without parameters (0.02s)
✔ TranslatorTest: Simple translation with parameters (0.02s)
✔ TranslatorTest: Translation with deeper level (0.02s)
--------------------------------------------------------------------------
Time: 00:09.936, Memory: 26.00 MB
OK (28 tests, 52 assertions)
Code Coverage Report Summary:
Classes: 75.00% (6/8)
Methods: 93.10% (27/29)
Lines: 98.59% (140/142)
For code coverage info run
$ docker-compose exec php-service ./vendor/bin/codecept run --coverage --coverage-html
and open tests/_output/coverage/index.html
in your browser
Static analyzer
$ docker-compose exec php-service ./vendor/bin/phpstan analyse src --level max