README

本软件包基于 PHP JSON tongue 构建，使用 JSON 文件将本地化功能引入 tightenco/jigsaw。

开始使用

需求

PHP 8.0 或更高版本。

设置

使用 composer 安装包

composer require elaborate-code/jigsaw-localization

通过在 bootstrap.php 中注册将 LoadLocalization 插件到构建器中

<?php

// bootstrap.php

use ElaborateCode\JigsawLocalization\LoadLocalization;

$events->beforeBuild([LoadLocalization::class]);

简单用法

定义翻译字符串

在项目的根目录中创建一个 lang 文件夹。
为每种语言/区域创建子文件夹。
使用 original text 作为 key，将翻译作为 value 填充子文件夹中的 JSON 文件。

文件结构示例

检索翻译字符串

源示例

<h2> {{ __($page, "Good morning", 'en') }} </h2>

<h2> {{ __($page, "programmer", 'es') }} </h2>

<h2> {{ __($page, "Good morning", 'fr') }} </h2>

输出结果

<h2> Good morning </h2>

<h2> programador </h2>

<h2> Bonjour </h2>

区域代码格式

两个或三个小写字母 作为语言代码 + 可选 一个连字符 (-) 和两个大写字母 作为区域代码。例如，以下所有代码 ar、es、fr-CA、haw-US 都被认为是有效的。

ISO 639-1 或 ISO 639-2 用于语言代码。
ISO 3166 用于区域代码。

多文件夹

为了组织目的，您可以使用多个 locale 键将国际化翻译分组到一个 JSON 中。

/lang
    ...
    /multi
        greetings.json
        projects_short_descriptions.json
        ...

greetings.json 示例

{
    "fr": {
        "Hello": "Salut",
        "Goodbye": "Au revoir"
    },
    "es": {
        "Hello": "Hola",
        "Goodbye": "Adiós"
    }
}

第一级键必须是区域代码！

使用文件夹结构作为区域代码前缀

默认区域

首先需要在 config.php 中定义 defaultLocale。如果没有设置，包将使用 en 作为默认值。

<?php

// config.php

return [
    // ...
    'defaultLocale' => 'es',
    // ...
];

翻译助手

如果您在调用 __ 助手时没有提供 locale 参数，它将尝试从页面路径中解析它。

echo __($page, $text);

如果您向 __ 助手提供 locale 参数，它将使用它并忽略文件夹结构。

文件夹结构

domain.com/{locale}/path

假设位于 Web 根目录文件夹 source 中的页面使用 defaultLocale 渲染。其他位于 以区域代码命名的子文件夹 中的页面，其 locale 设置为 子文件夹名称

/source
    /fr
        index.blade.php
        contact.blade.php
        about.blade.php
        ...
    /es
        index.blade.php
        contact.blade.php
        about.blade.php
        ...
    ...
    index.blade.php
    contact.blade.php
    about.blade.php
    ...

包含页面技巧

您可能会发现自己创建了一个完全编码的 source/index.blade.php，并在 source/fr/index.blade.php 和其他区域中重复相同的代码。为了避免这种情况，我们建议以下方法

创建一个 source/_pages 目录，其中将包含主页面。
主页面看起来像任何其他普通页面，它将具有 HTML 结构和对 __ 的调用，但没有硬编码的 $current_locale 值 。例如，您可以直接将 source/index.blade.php 的内容复制到 source/_pages/index.blade.php。
包含主页面到其他区域感知的页面中。
包含的内容将能够知道应用在翻译助手 __ 调用上的哪个 locale 作为 $current_locale。

/source
    /_pages
        index.blade.php
        contact.blade.php
        ...
    /fr
        index.blade.php
        contact.blade.php
        ...
    index.blade.php
    contact.blade.php
    ...

// Both /source/index.blade.php and /source/fr/index.blade.php
@include('_pages.index')

助手

重要：以下所有助手都将尝试在需要时从路径中解析区域代码！

在配置文件中设置 baseUrl 对于您的网站根URL不是 'domain.com/index.html' 是必要的。

current_path_locale

返回由路径推导出的 当前页面语言。

current_path_locale($page) // ar | es | fr-CA | haw-US

使用示例

<!DOCTYPE html>
<html lang="{{ current_path_locale($page) }}">
    <head>
    <!-- ... -->

translate_path

当您有一个在许多语言环境中都有的页面时，translate_path 帮助您获取等效的翻译 路径。

translate_path($page, $target_locale)

输入/输出示例

使用示例

<nav>
    @foreach(['en', 'es', 'fr'] as $locale)
        <a href="{{ translate_path($page, $locale) }}"> {{ $locale }} </a>
    @endforeach
</nav>

translate_url

与 translate_path 辅助函数类似，但若配置文件中设置了 baseUrl，则会在前面添加 baseUrl。

translate_url($page, $target_locale)

locale_path

为了避免在 paths 中硬编码 current_locale，只需将 locale code 部分之后的部分路径输入到这个辅助函数中，它会为您处理剩余的部分。

locale_path($page, $partial_path)

locale_url

与 locale_path 辅助函数类似，但若配置文件中设置了 baseUrl，则会在前面添加 baseUrl。

locale_url($page, $partial_path)

实时测试

想看看使用这个库的项目吗？请查看这个仓库

待办事项

测试非 A-Z 语言的行为。
添加带命名路由的路由器
- 允许自定义路由模式（例如设置 /blog/{locale}/）

贡献

任何帮助都非常欢迎，请随意分叉和PR :)

elaborate-code / jigsaw-localization

维护者

详细信息