README

Yii 消息翻译器

此包允许将消息翻译成多种语言。它可以与基于Yii的应用程序以及独立的PHP应用程序一起工作。

要求

PHP 8.0或更高版本。

安装

可以使用Composer安装此包。

composer require yiisoft/translator

额外包

有两种类型的额外包。消息源提供对各种消息存储格式的支持，如PHP数组或GNU gettext。消息格式化器提供在翻译消息中识别的额外语法。

消息源

translator-message-php - PHP文件消息存储。
translator-message-db - 数据库消息存储。
translator-message-gettext - gettext消息存储。

内置消息格式化器

简单格式化器仅替换消息中的参数。不考虑区域设置。
intl格式化器利用PHP intl扩展的消息格式化功能。

提取消息

通过控制台提取器执行消息提取，该提取器搜索翻译器消息调用并构建翻译文件。

在某些情况下，您可能需要在没有使用控制台的情况下这样做。如果是这种情况，请查看提取器指南。

配置

快速开始

首先，获取事件分发器的配置实例。当使用框架时，通常这样做

public function actionProcess(\Psr\EventDispatcher\EventDispatcherInterface $eventDispatcher)
{
    // ...
}

配置取决于使用的容器，因此下面我们将手动创建一个实例。

/** @var \Psr\EventDispatcher\EventDispatcherInterface $eventDispatcher */
$locale = 'ru';
$fallbackLocale = 'en';

$translator = new Yiisoft\Translator\Translator(
    $locale,
    $fallbackLocale,
    $eventDispatcher
);

$fallbackLocale和$eventDispatcher是可选的。后备区域设置用于在主区域设置中找不到翻译时。事件分发器用于调度缺失翻译事件。

现在我们有了实例，但它不知道从哪里获取翻译。让我们告诉它

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

// Now get an instance of CategorySource.
$category = new Yiisoft\Translator\CategorySource(
    $defaultCategoryName, 
    $messageSource,
    $formatter
);

// And add it.
$translator->addCategorySources($category);

就是这样。翻译器已准备好使用。

Yii3应用的高级配置

安装包后，您将在应用程序配置中找到以下配置文件

config/packages/yiisoft/translator/common.php
config/packages/yiisoft/translator/params.php

您需要获取MessageReader和MessageSource的实现来完成配置。请参阅“额外包”，“消息源”。

以下配置是在安装了所有必需包之后为Yii3应用所做的

您需要在common.php和params.php文件中取消注释围绕ApplicationCategorySource的字符串

<?php
declare(strict_types=1);

use Psr\EventDispatcher\EventDispatcherInterface;
use Yiisoft\Definitions\Reference;
use Yiisoft\Translator\TranslatorInterface;
use Yiisoft\Translator\Translator;
use Yiisoft\Translator\CategorySource;

/** @var array $params */

return [
    
    // Configure application CategorySource 
    ApplicationCategorySource::class => [ // <- Uncommented
        'class' => CategorySource::class,
        '__construct()' => [
            'name' => $params['yiisoft/translator']['defaultCategory'],
        ],
    ],
    
    TranslatorInterface::class => [
        'class' => Translator::class,
        '__construct()' => [
            $params['yiisoft/translator']['locale'],
            $params['yiisoft/translator']['fallbackLocale'],
            Reference::to(EventDispatcherInterface::class),
        ],
        'addCategorySources()' => [
            $params['yiisoft/translator']['categorySources']
        ],
    ],
];

和params.php

<?php

declare(strict_types=1);

use Yiisoft\Definitions\Reference;

return [
    'yiisoft/translator' => [
        'locale' => 'en-US',
        'fallbackLocale' => null,
        'defaultCategory' => 'app',
        'categorySources' => [
            // You can add categories to your application and your modules using `Reference::to` below
            Reference::to(ApplicationCategorySource::class), // <- Uncommented
            // Reference::to(MyModuleCategorySource::class),
        ],
    ],
];

多个翻译源

/** @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->addCategorySources($additionalCategory);

一次性添加多个类别源

/** 
 * @var \Yiisoft\Translator\TranslatorInterface $translator
 * @var \Yiisoft\Translator\CategorySource $additionalCategory1
 * @var \Yiisoft\Translator\CategorySource $additionalCategory2 
 */

$translator->addCategorySources($additionalCategory1, $additionalCategory2);

覆盖翻译消息

如果您使用了一个具有消息翻译的模块并想重新定义默认翻译消息，您可以使用与模块中使用的相同的categoryName添加您的类别源。

在翻译过程中，从后向前使用CategorySource，允许覆盖相同类别和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->addCategorySources($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();

获取一个默认使用指定区域设置的新的翻译器实例，如果未明确指定区域设置

$newDefaultLocale = 'de-DE';
echo $translator->withLocale($newDefaultLocale);

获取一个默认使用指定类别的新的翻译器实例，如果未明确指定类别

$newDefaultCategoryId = 'module2';
echo $translator->withDefaultCategory($newDefaultCategoryId);

附加信息

该包包含用于开发自定义格式化程序、读取器和编写器的接口。

文档

指南：英文，葡萄牙语 - 巴西
内部机制

如果您需要帮助或有问题，请访问Yii 论坛。您还可以查看其他Yii 社区资源。

许可证

Yii 消息翻译器是免费软件。它根据BSD许可证条款发布。有关更多信息，请参阅LICENSE。

由Yii 软件维护。

yiisoft /translator

维护者

详情