README

Leaf Omniglot

Leaf Omniglot 是一个简单但强大的模块，可以为您的 leaf 应用程序添加多语言功能。

安装

您可以使用 Composer 轻松安装 Leaf Omniglot。

composer require crosa7/leaf-omniglot

快速入门指南

创建翻译文件夹和文件

// Create a folder named "locales" in your project root
// (you can also create in another place that makes more sense, just be aware to configure the path accordingly)

// Create the following file inside the "locales" folder
en_US.locale.json

// With the following content
{
    "welcome.title": "Hello World"
}

初始化 Omniglot

在您的 index.php 文件中（如果使用 MVC：public/index.php）。添加以下行

omniglot()->init(
    [
        'TRANSLATION_FILES_LOCATION' => './locales',
    ]
);

添加语言切换路由

在您的路由文件中（MVC 的 "_app.php" 和基础 Leaf 的 "index.php"）添加以下行

omniglot()->addLanguageSwitchRoute();

开始翻译

现在在您的模板文件中，您可以添加以下内容

（此示例使用 laravel blade 作为模板引擎，但您可以根据您的模板引擎进行调整）

<form method="post" action="/language/switch">
  <select name="locale" onchange="this.form.submit()">
    @foreach(omniglot()->getAvailableLocales() as $locale)
        <option value="{{ $locale }}" {{ omniglot()->getCurrentLocale() === $locale ? 'selected' : '' }}>{{ $locale }}</option>
    @endforeach
  </select>
</form>

<h1>{{ tl('welcome.title') }}</h1>

或者在简单的 index.php 文件中

<form method="post" action="/language/switch">
    <select name="locale" onchange="this.form.submit()">
      <?php
	foreach(omniglot()->getAvailableLocales() as $locale) {
            if (omniglot()->getCurrentLocale() === $locale) {
                echo '<option value=' . $locale .' selected>' . $locale . '</option>';
            } else {
                echo '<option value=' . $locale .'>' . $locale . '</option>';
            }
	}
      ?>
    </select>
</form>

<h1><?php echo tl('welcome.title') ?></h1>

现在您应该在浏览器中看到一个下拉菜单，其中包含 "en_US" 作为选项，并在 "h1" 标签中包含文本：Hello World

现在您可以添加另一个具有相同翻译键但不同值的翻译文件
现在下拉菜单中有一个新的选项，并且您可以点击它来切换语言。

例如

// Create the following file inside the "locales" folder
pt_PT.locale.json

// With the following content
{
    "welcome.title": "Ola Mundo"
}

现在如果您切换到下拉菜单中的 "pt_PT"，您应该看到文本：Ola Mundo

基本用法

安装 Omniglot 后，您需要创建一个文件夹，您的翻译文件将存储在该文件夹中。在该文件夹内，您将创建以下格式的文件

en_US.locale.json
pt_PT.locale.json

重要的是要有一个以 .locale.json 结尾的文件，语言名称不重要。例如，您可以使用 en.locale.json

翻译文件内容

您的翻译文件应具有以下格式

{
    "welcome.page.title": "This is the page title translation",
    "welcome.page.sub_title": "This is welcome page subtitle"
}

在 JSON 中的键是翻译键，用于标识翻译，而值是在您在文件名中定义的语言中翻译本身

初始化

初始化模块并传递您自定义的配置

omniglot()->init([
    'DEFAULT_LOCALE' => 'en_US',
    'TRANSLATION_FILES_LOCATION' =>  './locales',
]);

配置

以下是在上面的 init() 方法中可以传递的可用配置参数。

DEFAULT_LOCALE

使用此参数定义您的默认区域设置，这样它就是应用程序加载时使用的初始区域设置。 此处配置的值必须与您为此区域设置定义的翻译文件名匹配。 示例

DEFAULT_LOCALE => en_US

// Translation file name
en_US.locale.json

TRANSLATION_FILES_LOCATION

如名称所示，这是包含翻译文件的文件夹的路径，建议如下：'TRANSLATION_FILES_LOCATION' => './locales' 然后将翻译文件放入 locales 文件夹中。

LOCALE_STRATEGY

使用此选项定义您想要 Omniglot 在获取和存储所选区域设置时的行为方式。可能的值是： session、accept-language-header 和 custom。

• session: 这对于 MVC/网站设置很有用。当您使用 omniglot 并调用 setCurrentLocale 或 getCurrentLocale 时，当前区域设置将被获取/存储在会话中。
• accept-language-header: 当您只使用Leaf作为API时，这个功能很有用。您只需将Accept-Language头设置为要使用的区域设置值，Omniglot将根据此区域设置进行翻译。setCurrentLocale在这里不会做任何事情，因为在这种用例中，只有调用API的外部应用程序设置区域设置。
• 自定义: 这是一个更高级的选项。Omniglot 允许您创建自己的区域设置获取/存储策略。为此，您需要创建一个实现LocaleStrategyPluginInterface的类。此接口有两个方法
  • getCurrentLocale(): 应返回一个包含区域设置名称的字符串。
  • setCurrentLocale(): 用于存储当前区域设置（如果需要）。不返回任何内容。

CUSTOM_LOCALE_STRATEGY_CLASS_NAME

在将LOCALE_STRATEGY设置为custom并实现上述接口的类之后。
在此处设置您新类的类名，例如

// Your class: RequestLocaleStrategy
CUSTOM_LOCALE_STRATEGY_CLASS_NAME => RequestLocaleStrategy::class

可用方法

tl()

您可以在功能模式下从任何地方调用此方法，这是翻译字符串的主要方法。此方法接受两个参数

• key: 在翻译文件中定义的翻译键
• params: 包含您在翻译文件中定义的参数的数组，例如

// Translation file content
{
    "welcome.page.title": "Welcome %firstName% --lastName-- to the dashboard",
    "navbar.title": "Dashboard"
}

// Translation method call
tl('welcome.page.title', ['%firstName%' => 'John', '--lastName--' => 'Doe']); // Welcome John Doe to the dashboard

// You can use anything as parameter identifier. Omniglot will look for anything that you pass as key  
// in the parameters array and replace anything that it finds with this pattern and replace by the value you pass.

// In case of translations without parameters you can simply call:
tl('navbar.title'); // Dashboard

omniglot()

此方法允许您使用Omniglot类中的任何方法。例如，您可以使用omniglot()->translate()而不是tl()。在omniglot()下有下列方法可用

• omniglot()->init(): 如基本用法中所述
• omniglot()->translate(): 与tl()相同
• omniglot()->setCurrentLocale(): 用于根据所选策略设置当前选定的区域设置
• omniglot()->getCurrentLocale(): 获取当前配置的区域设置或尚未配置时的默认区域设置
• omniglot()->getAvailableLocales(): 返回可用区域设置的数组。这是从配置的locales文件夹的文件名中获取的
• omniglot()->getDefaultLocale(): 如其名所示，返回配置的默认区域设置

omniglot()->addLanguageSwitchRoute()

您可以在定义路由的同一文件中调用此方法。对于Leaf MVC / API，这将是_app。
对于简单的Leaf应用程序，它将在index.php中。

这将自动为您创建一个POST路由，以便在您想要切换语言时调用。
您只需向/language/switch发送POST请求，并包含以下POST数据

{
    "locale": "en_US"
}

如果存在相应的文件，它将设置此为当前区域设置。它也会将您重定向回之前调用的页面。

它还接受3个参数。

• path: 默认情况下，定义的路径为/language/switch，但您可以传递任何您想要的路径
• requestLocaleParamName: 默认情况下，该路由期望带有默认属性名为locale的POST数据，但可以通过此参数进行更改
• redirectToReferer: 默认情况下，此路由将自动重定向到引用者，但您可以将此设置为false，然后它将只返回一个简单的JSON响应

链接/项目

• Leaf文档