README

摘要

这是 Whoa 框架的本地化组件Whoa Framework。

该组件可以帮助将应用程序翻译成不同的语言。特别是，它提供了一种轻松管理本地化文件和提取给定区域设置的本地化字符串的能力，并提供默认值。

消息本地化

对于给定的资源存储数据（稍后介绍）的用法如下

    $storage   = new BundleStorage($storageData);
    $localized = $storage->get('de_AT', 'ErrorMessages', 'id_or_message');

其中

• 第一个参数 de_AT 是区域代码。
• 第二个参数 ErrorMessages 是消息的命名空间名称。使用命名空间可以在命名空间之间隔离消息。通常命名空间是一个没有 .php 文件扩展名的资源文件名。
• 第三个参数 id_or_message 是消息标识符。消息标识符应该在命名空间内是唯一的。

它首先找到最接近的区域（de_AT、de 或默认的例如 en，如果没有找到区域）和相应的消息。

结果将包含找到的消息及其区域。例如

    // $localized
    ['Hallo Welt', 'de'];

如果存在请求的区域 de_AT 的资源，结果可能如下所示

    // $localized
    ['Hallo Welt aus Österreich', 'de_AT'];

资源存储

在上面的示例中，资源存储数据是一个包含本地化字符串的数组。引入此对象的原因是性能优化。在文件系统中查找多个文件并分析它们的数据是费时费力的。存储数据用单个优化的搜索数组替换了许多资源文件，该数组可以被缓存。

例如，有一个资源文件夹结构

Resources
    |_ de
        |_ Messages.php
    |_de_AT
        |_ Messages.php

其中 Messages.php 是一个普通的 PHP 数组文件

<?php
return [
    'Hello World' => 'Hallo Welt',
];

和

<?php
return [
    'Hello World' => 'Hallo Welt aus Österreich',
];

然后，可以创建一个存储数组

    $storageData = (new FileBundleEncoder('path/to/ResourcesFolder/'))->getStorageData('de');

方法 getStorageData 的第一个参数是默认区域代码。

最后，完整示例

    $storageData = (new FileBundleEncoder('path/to/ResourcesFolder/'))->getStorageData('de');
    $localized = (new BundleStorage($storageData))->get('de_AT', 'ErrorMessages', 'Hello World');
    // $localized
    ['Hallo Welt aus Österreich', 'de_AT'];

消息翻译

除了资源存储之外，该软件包还提供了一个针对 MessageFormatter 的有用包装。

    $storageData = (new FileBundleEncoder('path/to/ResourcesFolder/'))->getStorageData('en');
    $translator = new Translator(new BundleStorage($storageData));

    // 'Hallo Welt' (message is in the resources)
    $translator->translateMessage('de', 'Messages', 'Hello World');

    // 'Hallo Welt aus Österreich' (message is in the resources)
    $translator->translateMessage('de_AT', 'Messages', 'Hello World');

    // 'Good morning' (message not found in resources so it returns the key itself)
    $translator->translateMessage('de', 'Messages', 'Good morning');

方法 translateMessage 的签名是 translateMessage(string $locale, string $namespace, string $key, array $args = []): string。该方法可以通过 $args 参数接受格式化参数。有关高级格式化示例，请参阅 MessageFormatter::formatMessage。

还有一个针对 Translator 的包装器，称为 Formatter，它隐藏了区域代码和命名空间。它可以在为登录用户定义了当前会话区域的环境中使用。所以代码基本上是请求当前区域和指定命名空间的 FormatterInterface。

    $formatter = new Formatter('de', 'Messages', $translator);

    // 'Hallo Welt'
    $formatter->formatMessage('Hello World');

更多信息.

推荐用法

• 为您的应用程序创建一个包含所需区域的资源文件夹。
• 对于资源文件夹和默认区域，使用 FileBundleEncoder 创建存储数据并将其缓存。
• 在页面加载时，从缓存中读取存储数据并将其加载到 Translator 中，使用 BundleStorage。
• 使用翻译器进行消息格式化。

测试

$ composer test