README

摘要

这是 Limoncello 框架的本地化组件。

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

消息本地化

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

    $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。

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

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

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

更多信息.

推荐用法

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

测试

$ composer test