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