Spiral i18n 组件基于 symfony/translator 包，并提供兼容的接口。Web 扩展包默认包含了此扩展。
要在其他构建中启用此扩展，请：
composer require spiral/translator
在您的应用程序中注册引导程序 I18nBootloader。
public function defineBootloaders(): array
{
return [
// ...
\Spiral\Bootloader\I18nBootloader::class,
// ...
];
}
阅读更多关于引导程序的信息，请参阅 框架 — 引导程序 部分。
默认情况下，翻译器组件将自动加载位于 app/locale/{lang} 目录下的所有 locale 文件。
要获取可用 locale 列表：
namespace App\Endpoint\Web;
use Spiral\Translator\TranslatorInterface;
class HomeController
{
public function index(TranslatorInterface $translator): void
{
dump($translator->getCatalogueManager()->getLocales());
}
}
要更改 locale，请使用 setLocale 方法。
注意 建议在中间件或领域核心中使用
setLocale方法，然后适当地重置原始 locale。
框架自动提供一个默认配置，位于 Spiral\Bootloader\I18nBootloader 中。如果您需要自定义设置，可以在 app/config/translator.php 中定义它们：
以下是一个典型的配置示例：
use Symfony\Component\Translation\Dumper;
use Symfony\Component\Translation\Loader;
return [
'locale' => env('LOCALE', 'en'),
'fallbackLocale' => env('LOCALE', 'en'),
'directory' => directory('locale'),
'autoRegister' => env('DEBUG', true),
// available locale loaders (the key is extension)
'loaders' => [
'php' => Loader\PhpFileLoader::class,
'po' => Loader\PoFileLoader::class,
'csv' => Loader\CsvFileLoader::class,
'json' => Loader\JsonFileLoader::class
],
// export methods
'dumpers' => [
'php' => Dumper\PhpFileDumper::class,
'po' => Dumper\PoFileDumper::class,
'csv' => Dumper\CsvFileDumper::class,
'json' => Dumper\JsonFileDumper::class,
],
'domains' => [
// by default we can store all messages in one domain
'messages' => ['*']
]
];
关键点：
locale 是您的主要语言，而 fallbackLocale 是应用程序在指定的语言不可用时将使用的默认语言。app/locale 目录。如果您想为您的语言文件使用不同的目录，请修改 directory 选项：
return [
'directory' => directory('locale'),
];
有时，您可能需要来自多个位置的翻译。例如，当您使用带有自己翻译的外部包时。
要指定多个目录，请使用 directories：
return [
'directory' => directory('locale'),
// ...
'directories' => [
directory('vendor/package/name/locale'),
...
],
// ...
];
您也可以使用 Spiral\Bootloader\I18nBootloader 引导程序添加新目录：
use Spiral\Boot\Bootloader\Bootloader;
use Spiral\Bootloader\I18nBootloader;
final class AppBootloader extends Bootloader
{
public function init(I18nBootloader $i18n): void
{
$i18n->addDirectory('some/directory');
}
}
注意 如果翻译文件之间存在冲突，主应用程序中的文件将优先于其他目录。
可以将应用程序 locale 包导出为以下格式：
要导出应用程序 locale 包，请运行：
php app.php i18n:export en ./
注意 将 locale
en导出到当前目录。
您应该看到在该目录下创建了文件 messages.en.php。要以其他格式导出：
php app.php i18n:export en ./ -d po
此命令将 locale 导出为 GetText 格式。
框架能够使用静态代码索引自动生成 locale 文件。 运行命令 i18n:index 以查找所有声明的字符串。
php app.php i18n:index -vv
将 locale 导入到项目中，将文件放置在 app/locale/{lang} 目录中。使用 GetText、PHP 或 JSON 格式。
Spiral 包含一个适用于 Twig 和 Stempler 引擎的视图处理过程，用于翻译视图源代码。 翻译后的视图将存储在单独的视图缓存中，并且它提供了在没有任何性能损失的情况下翻译视图的能力。
要激活视图翻译，请启用引导程序 Spiral\Bootloader\Views\TranslatedCacheBootloader。 确保在视图引擎引导程序之前添加此引导程序：
public function defineBootloaders(): array
{
return [
// ...
\Spiral\Views\Bootloader\ViewsBootloader::class,
\Spiral\Bootloader\Views\TranslatedCacheBootloader::class,
// ...
];
}
阅读更多关于引导程序的信息，请参阅 框架 — 引导程序 部分。
在您的模板中使用 [[ string ]] 包裹要翻译的字符串：
[[hello world]]
注意 在您的应用程序中更改 locale 以切换视图中的翻译。
可以使用专门的 trait Spiral\Translator\Traits\TranslatorTrait 将翻译功能添加到任何应用程序对象。
我们可以将翻译器 trait 添加到控制器：
namespace App\Endpoint\Web;
use Spiral\Translator\Traits\TranslatorTrait;
class HomeController
{
use TranslatorTrait;
public function index(): string
{
return $this->say('hello world!');
}
}
注意 运行 'i18n:index' 以索引字符串调用。
在消息由逻辑定义且无法索引的情况下，使用常量或属性来声明类消息，每个用 [[]] 包裹的字符串都将被自动索引。
class HomeController
{
use TranslatorTrait;
protected const MESSAGES = [
'error' => '[[An error]]',
'success' => '[[Success]]'
];
public function index(): string
{
echo $this->say(self::MESSAGES['error']);
}
}
| 事件 | 描述 |
|---|---|
| Spiral\Translator\Event\LocaleUpdated | 此事件将在更改 locale 后 触发。 |
注意 要了解更多关于调度事件的信息，请参阅我们文档中的 事件 部分。