jrmajor/fluent

PHP 的 Fluent 本地化系统

资助包维护!
jrmajor

v1.0.1 2023-12-01 21:40 UTC

README

Latest Stable Version Required PHP Version

A PHP implementation of the Project Fluent, a localization system designed by Mozilla to unleash the expressive power of the natural language.

阅读 Fluent 语法指南 或在 Fluent 游乐场 中试用,以了解更多关于语法的知识。

shared-photos =
    { $userName } { $photoCount ->
        [one] added a new photo
       *[other] added { $photoCount } new photos
    } to { $userGender ->
        [male] his stream
        [female] her stream
       *[other] their stream
    }.
$bundle->message('stream.shared-photos', [
    'userName' => 'jrmajor',
    'photoCount' => 2,
    'userGender' => 'male',
]); // jrmajor added 2 new photos to his stream.

您可以通过 Composer 安装此包: composer require jrmajor/fluent

使用 jrmajor/laravel-fluent 将 Fluent 翻译集成到您的 Laravel 应用程序中。

用法

解析

use Major\Fluent\Parser\FluentParser;

$parser = new FluentParser(strict: true);

$resource = $parser->parse('hello-user = Hello, { $userName }!');

$strict 构造函数参数默认为 false。在严格模式下,语法错误会导致 ParserException。否则,它们将被忽略,并以 Junk 的形式表示在 AST 中。

消息格式化

use Major\Fluent\Bundle\FluentBundle;

$bundle = new FluentBundle('en', strict: true);

$bundle->addResource($resource);
// or
$bundle->addFtl('hello-user = Hello, { $userName }!');

$bundle->message('hello-user', userName: 'World'); // Hello, World!

FluentBundle 是单一语言的翻译资源存储库。其构造函数接受以下参数

  • string $locale: 实例化特定区域设置的格式化程序的区域设置(例如 en-US, pl, zh-Hant-TW, fr-CA)。
  • bool $strict = false: 查看 处理错误
  • bool $useIsolating = true: 指定是否使用 Unicode 隔离标记(FSI,PDI)进行双向插值。
  • bool $allowOverrides = false: 允许覆盖现有消息和术语。

添加资源

可以通过 addResource()addFtl() 方法将翻译添加到包中。第一个接受解析器返回的 FluentResource 对象,而第二个接受原始 FTL 字符串。

addResource(FluentResource $resource, bool $allowOverrides = null): static

addFtl(string $ftl, bool $allowOverrides = null): static

如果 $allowOverridesnull,则使用包的默认设置。

如果包处于严格模式,则 $ftl 解析也将以严格模式进行。

格式化消息

message(string $_message, mixed ...$arguments): ?string

message() 方法接受消息 ID 作为第一个参数,并将消息参数作为命名参数。对于缺失的消息,它返回 null

welcome = Welcome
    .guest = Welcome, Guest
    .user = Welcome, { $userName }
$bundle->message('welcome'); // Welcome

$bundle->message('goodbye'); // null

对于属性,您可以使用“点”表示法

$bundle->message('welcome.guest'); // Welcome, Guest

消息参数可以作为命名参数或关联数组传递

$bundle->message('welcome.user', userName: 'John'); // Welcome, John
// equivalent to
$bundle->message('welcome.user', ['userName' => 'John']); // Welcome, John

处理错误

默认情况下,所有解析器异常都会被忽略,并可以使用 popErrors() 方法获取。它返回一个异常数组并清除异常缓存,这意味着下一次您调用它时,它将只返回新的错误。

$bundle->message('welcome.user'); // Welcome, {$userName}

$errors = $bundle->popErrors();

count($errors);           // 1
$errors[0]->getMessage(); // Unknown variable: $userName.

所有解析器异常都扩展 ResolverException。在严格模式下,它们会在 message() 调用中立即抛出。

测试

vendor/bin/phpunit           # Tests
vendor/bin/phpstan analyze   # Static analysis
vendor/bin/php-cs-fixer fix  # Formatting