This package allows translating messages into several languages. It can work with both Yii-based applications and standalone PHP applications.
The preferred way to install this package is through Composer:
composer require yiisoft/translatorThere are two types of additional packages. Message source provide support of various message storage formats such as PHP arrays or GNU gettext. Message formatters provide extra syntax that is recognized in translated messages.
- translator-message-php - PHP file message storage.
- translator-message-db - Database message storage.
- translator-message-gettext - gettext message storage.
- translator-formatter-intl - Intl (i18n) formatter
- translator-formatter-simple - Simple formatter to use if you do not need additional syntax such as in case with gettext message source.
First, get a configured instance of event dispatcher. When using a framework it is usually done as:
public function actionProcess(\Psr\EventDispatcher\EventDispatcherInterface $eventDispatcher)
{
// ...
}Configuration depends on the container used so below we'll create an instance manually.
/** @var \Psr\EventDispatcher\EventDispatcherInterface $eventDispatcher */
$locale = 'ru';
$fallbackLocale = 'en';
$translator = new Yiisoft\Translator\Translator(
$locale,
$fallbackLocale,
$eventDispatcher
);$fallbackLocale and $eventDispatcher are optional. Fallback locale is used when no translation was found in the
main locale. Event dispatcher is used to dispatch missing translation events.
Now we've got an instance, but it has no idea where to get translations from. Let's tell it:
// Default category is used when no category is specified explicitly.
$defaultCategoryName = 'app';
$pathToTranslations = './messages/';
// We use MessageSource that is based on PHP files.
$messageSource = new \Yiisoft\Translator\Message\Php\MessageSource($pathToTranslations);
// We use Intl message formatter.
$formatter = new \Yiisoft\Translator\Formatter\Intl\IntlMessageFormatter();
// Now get an instance of CategorySource.
$category = new Yiisoft\Translator\CategorySource(
$defaultCategoryName,
$messageSource,
$formatter
);
// And add it.
$translator->addCategorySource($category);
That's it. Translator is ready to be used.
/** @var \Yiisoft\Translator\TranslatorInterface $translator */
$categoryName = 'module';
$pathToModuleTranslations = './module/messages/';
$moduleMessageSource = new \Yiisoft\Translator\Message\Php\MessageSource($pathToModuleTranslations);
// Simple message formatter.
$formatter = new \Yiisoft\Translator\Formatter\Simple\SimpleMessageFormatter();
$additionalCategory = new Yiisoft\Translator\CategorySource(
$categoryName,
$moduleMessageSource,
$formatter
);
$translator->addCategorySource($additionalCategory);/** @var \Yiisoft\Translator\TranslatorInterface $translator */
/** @var \Yiisoft\Translator\CategorySource $additionalCategory1 */
/** @var \Yiisoft\Translator\CategorySource $additionalCategory2 */
$translator->addCategorySources([
$additionalCategory1,
$additionalCategory2,
]);If you use a module that has message translation and want to redefine default translation messages, you can
add your category source with the same categoryName as used in the module.
During translation CategorySources are used from last to first allowing overriding messages of the same
category and ID.
/** @var \Yiisoft\Translator\TranslatorInterface $translator */
/** @var \Yiisoft\Translator\Message\Php\MessageSource $yourCustomMessageSource */
/** @var \Yiisoft\Translator\Formatter\Simple\SimpleMessageFormatter $formatter */
// CategorySource for module with "validator" category name.
$categoryNameAsModule = 'validator'; //
$moduleCategorySource = new Yiisoft\Translator\CategorySource(
$categoryNameAsModule,
$yourCustomMessageSource,
$formatter
);
// Needs be added after module category source is added.
$translator->addCategorySource($moduleCategorySource);// single translation
$messageIdentificator = 'submit';
echo $translator->translate($messageIdentificator);
// output: `Submit message`
// translation with plural
$messageIdentificator = 'multiHumans';
echo $translator->translate($messageIdentificator, ['n' => 3]);
// output: `3 humans`$messageIdentificator = 'submit';
echo $translator->translate($messageIdentificator, [], 'moduleId', 'ru');
// output: `Отправить сообщение`$newDefaultLocale = 'de-DE';
$translator->setLocale($newDefaultLocale);echo $translator->getLocale();Get a new Translator instance with a locale to be used by default in case locale isn't specified explicitly.
$newDefaultLocale = 'de-DE';
echo $translator->withLocale($newDefaultLocale);Get a new Translator instance with a category to be used by default in case category isn't specified explicitly.
$newDefaultCategoryId = 'module2';
echo $translator->withCategory($newDefaultCategoryId);The package contains interfaces for development of custom formatters, readers, and writers.
The package is tested with PHPUnit. To run tests:
./vendor/bin/phpunitThe package tests are checked with Infection mutation framework. To run it:
./vendor/bin/infectionThe code is statically analyzed with Psalm. To run static analysis:
./vendor/bin/psalm
The Yii Message Translator is free software. It is released under the terms of the BSD License.
Please see LICENSE for more information.
Maintained by Yii Software.