README

Turjuman 是一个用于简化生成本地化路由过程的 Laravel 路由本地化包。名称 "turjuman" 来自阿拉伯语单词 تُرجُمان，意为翻译或本地化的人。这个名字具有历史意义，因为它曾是先知穆罕默德的一位同伴alsahaba（同伴）的名字之一，即阿卜杜拉·本·阿巴斯。尽管他是最年轻的同伴之一，但他因其对神圣的古兰经的著名解释能力而获得了“turjuman”（解释者）的头衔，真主祝福他，愿他安息。

安装

Turjuman 与 Laravel 10 及以上版本兼容。

使用 Composer 安装包

composer require alnaggar/turjuman

然后，发布配置文件

php artisan vendor:publish --provider="Alnaggar\Turjuman\TurjumanServiceProvider"

然后，在 app/http/kernel.php 中的 \Illuminate\Routing\Middleware\SubstituteBindings 中间件之前注册这些中间件

 'web' => [
    // ...

    \Alnaggar\Turjuman\Middleware\SetLocale::class,
    \Alnaggar\Turjuman\Middleware\LocalizeRoutes::class,
    \Illuminate\Routing\Middleware\SubstituteBindings::class,
],

配置

配置文件 (config/turjuman.php) 提供了在定义支持的本地化、默认本地化、显示选项、隐藏默认本地化、路由别名和本地化标识符方面的灵活性。

支持的本地化

supported_locales 键允许您指定您想要支持的本地化。有超过 800 个本地化可供选择，您可以根据项目需求取消注释或添加新的本地化。每个本地化都可以通过相应的 Locale 实例自定义附加属性，例如货币、国家等，使其可通过相应的属性访问。

注意

确保符合 ISO 15897 对于本地化代码和语言目录的要求，如 Laravel 推荐的，以获得更好的体验。

默认本地化

default_locale 键设置默认本地化的代码。当没有检测到本地化时，Turjuman 将回退到该本地化。

在 URL 中显示本地化

display_location 键控制本地化在 URL 中的显示方式。它可以是一个正整数，表示要显示的段，一个指定显示查询名称的字符串，或者 null 以隐藏 URL 中的本地化，同时将其内部设置。

隐藏默认本地化

当 hide_default 键设置为 true 时，确定是否在可显示的情况下在 URL 中显示默认本地化。

路由别名

route_aliases 键允许您在不同本地化中翻译特定的 URL。例如，您可以通过在相应的本地化键下添加它们来提供自定义 slug 和/或域名。

本地化标识符

locale_identifier 键允许您设置用于在 URL 参数、会话、cookie 和表单输入中识别当前本地化的本地化令牌名称。

中间件

`SetLocale.php` 中间件

此中间件负责根据预定义的顺序基于各种来源设置当前本地化，例如请求输入、URL、会话、cookie、浏览器语言和用户偏好，以确定当前本地化。

除此之外，您还有通过 artisan 命令发布名为 TurjumanSetLocale 的中间件的选项

php artisan turjuman:middleware

通过这种方式，您可以轻松地覆盖此中间件中的 fetchUserLocale(): ?string 函数。该函数允许您从数据库或其他来源检索用户的首选区域设置，如果它未在预定义源中确定。发布后，将 app/http/kernel.php 中的现有 \Alnaggar\Turjuman\Middleware\SetLocale::class 中间件替换为 \App\Http\Middleware\TurjumanSetLocale::class 中间件。这提供了一种方便的方式来自定义用户首选区域设置的检索方式，使您可以根据具体需求进行调整。

`LocalizeRoutes.php` 中间件

此中间件负责根据当前的区域设置处理路由的本地化。它检查请求是否为 GET 请求以及当前路由是否已本地化。它确保 URL 与本地化 URL 匹配，如果不匹配，则重定向到正确的 URL。

功能

路由本地化

利用分组函数，轻松创建针对不同语言或地区的本地化路由。

//  routes/web.php
use Alnaggar\Turjuman\Turjuman;

Turjuman::group(function(){
    Route::get('/', function(){
        return view('welcome');
    });

    Route::get('/show/{id}', ['\App\Http\Controllers\UserController::class', 'index']);

    Route::post('/edit/{id}', ['\App\Http\Controllers\UserController::class', 'update']);

    // ...
});

区域别名

您可以在区域设置的配置中为区域定义一个别名，使其出现在 URL 中，而不是区域代码。

// confing/turjuman.php

'supported_locales' => [
    'ar' => ['name' => 'Arabic', 'native' => 'العربية', 'script' => 'Arab', 'alias' => 'العربية'],
    'en' => ['name' => 'English', 'native' => 'English', 'script' => 'Latn', 'alias' => 'English'],
    'fr' => ['name' => 'French', 'native' => 'français', 'script' => 'Latn'], // no alias.

    // ...
],

本地化 URL 生成

根据配置的区域和分组属性生成本地化 URL。

use Alnaggar\Turjuman\Turjuman;

Turjuman::group(function () {
    // Define your localized routes here
}, [
    'route_aliases' => [
        'fr' => [
            '/products' => '/produits'
        ]
    ]
]);

use Alnaggar\Turjuman\Turjuman;

$url = Turjuman::getLocalizedUrl('/products', 'fr');
// Returns the URL for the 'fr' locale: '/fr/produits'

分组属性

为路由分组定义自定义属性以控制显示类型、默认区域等。

use Alnaggar\Turjuman\Turjuman;

Turjuman::group(function () {
    // Define your localized routes here
}, [
    'supported_locales' => [...], // Specify supported locales
    'default_locale' => 'en', // Set the default locale
    // Add more group attributes as needed
]);

可扩展和可宏化

通过添加宏和混入来扩展 Turjuman 的功能。

use Alnaggar\Turjuman\Turjuman;

// Adding Macros
Turjuman::macro('customMethod', function () {
    // Your custom logic here
});

/// Adding Mixins
Turjuman::mixin(new MyCustomMixin());

Alnaggar\Turjuman\Locale 和 Alnaggar\Turjuman\GroupAttributes 使用 Alnaggar\Turjuman\Traits\Extensible 特性，使其可宏化，并可能具有额外的属性。这些属性可以通过数组访问、属性访问或获取方法访问。

// config/turjuman.php

'supported_locales' => [
    'ar_DZ' => ['name' => 'Arabic (Algeria)', 'native' => 'العربية (الجزائر)', 'script' => 'Arab', 'currency' => 'DZD'],
    'ar_EG' => ['name' => 'Arabic (Egypt)', 'native' => 'العربية (مصر)', 'script' => 'Arab', 'currency' => 'EGP']
]

// ... other configurations

// routes/web.php

use Alnaggar\Turjuman\Turjuman;

Turjuman::group(function () {
    // Define your localized routes here
}, [
    'continent' => 'Africa',
    'common_language' => 'Arabic'
]);

// YourClass.php

use Alnaggar\Turjuman\Turjuman;

public function getDetails()
{
    $currency = Turjuman::getCurrentLocale()['currency'];
    $continent = Turjuman::getCurrentAttributes()->continent;
    $commonLanguage = Turjuman::getCurrentAttributes()->getCommonLanguage();

    // ...
}

注意

自定义属性必须使用 snake_case 命名。

仅在需要时进行重定向

重定向机制是选择性地应用的，仅在遇到 GET 请求时触发。对于其他类型的请求，区域将在内部设置，而不会启动任何重定向。

标准路由缓存

您可以像往常一样自由地使用 Laravel 的任何标准路由缓存命令。

用法

路由分组

`group(\Closure $routes, array $attributes = []): \Alnaggar\Turjuman\Group`

group 函数是一个强大的功能，允许您对本地化路由进行分组。它接受一个包含要本地化路由的闭包和可选属性。您可以添加自定义属性以覆盖配置属性，这使得它非常适合具有不同区域的多租户应用程序。

use Alnaggar\Turjuman\Facades\Turjuman;

Turjuman::group(function () {
    // Define your localized routes here
}, [
    'default_locale' => 'en',
    'display_location' => 'lang',
    // More custom attributes...
]);

`ignore(\Illuminate\Routing\Route|\Closure $routes): void`

在 group 闭包中使用 ignore 函数可以排除特定路由的本地化。它接受一个闭包或单个要忽略的路由。

use Alnaggar\Turjuman\Turjuman;

Turjuman::group(function () {
    // Define your localized routes here

    Turjuman::ignore(function() {
        // Define your non-localized routes here
    });
});

配置管理

`addConfigLocales(array $locales): \Alnaggar\Turjuman\Localizer`

将额外的区域添加到配置中支持的区域。

示例

// App/Providers/AppServiceProvider.php

use \Alnaggar\Turjuman\Locale;
use \Alnaggar\Turjuman\Turjuman;

$locales = [
    new Locale(['code' => 'fr', 'name' => 'French', 'native' => 'français', 'script' => 'Latn']),
    new Locale(['code' => 'es', 'name' => 'Spanish', 'native' => 'español', 'script' => 'Latn']),
];

Turjuman::addConfigLocales($locales);

`setConfigLocales(array $locales): \Alnaggar\Turjuman\Localizer`

设置配置中的支持区域。

示例

// App/Providers/AppServiceProvider.php

use \Alnaggar\Turjuman\Locale;
use \Alnaggar\Turjuman\Turjuman;

$locales = [
    // Define your locales.
];

Turjuman::setConfigLocales($locales);

`setConfigDefaultLocale(string $locale): \Alnaggar\Turjuman\Localizer`

设置配置的默认区域。

示例

// App/Providers/AppServiceProvider.php

use \Alnaggar\Turjuman\Turjuman;

Turjuman::setConfigDefaultLocale('fr');

`getConfigAttributes(): \Alnaggar\Turjuman\GroupAttributes`

检索配置属性。

示例

use \Alnaggar\Turjuman\Turjuman;

$configAttributes = Turjuman::getConfigAttributes();

分组信息

`getCurrentGroup(): ?\Alnaggar\Turjuman\Group`

检索负责本地化当前路由的 Alnaggar\Turjuman\Group 实例。如果未找到，则返回 null。

示例

use \Alnaggar\Turjuman\Turjuman;

$currentGroup = Turjuman::getCurrentGroup();

`getCurrentAttributes(): \Alnaggar\Turjuman\GroupAttributes`

检索当前分组属性。

示例

use \Alnaggar\Turjuman\Turjuman;

$currentAttributes = Turjuman::getCurrentAttributes();

区域管理

`setCurrentLocale(string $locale): \Alnaggar\Turjuman\Locale`

设置当前区域。

示例

use \Alnaggar\Turjuman\Turjuman;

Turjuman::setCurrentLocale('es');

`getLocale(string $locale): ?\Alnaggar\Turjuman\Locale`

根据其代码检索 Alnaggar\Turjuman\Locale 实例。如果该区域不受支持，则返回 null。

示例

use \Alnaggar\Turjuman\Turjuman;

$arabicLocale = Turjuman::getLocale('ar');

`getSupportedLocales(): array`

检索当前分组的支持区域。

示例

use \Alnaggar\Turjuman\Turjuman;

$supportedLocales = Turjuman::getSupportedLocales();

`getDefaultLocale(): \Alnaggar\Turjuman\Locale`

检索当前分组的默认区域实例。

示例

use \Alnaggar\Turjuman\Turjuman;

$defaultLocale = Turjuman::getDefaultLocale();

`getCurrentLocale(): ?\Alnaggar\Turjuman\Locale`

获取当前区域实例。如果当前路由未本地化，则返回 null。

示例

use \Alnaggar\Turjuman\Turjuman;

$currentLocale = Turjuman::getCurrentLocale();

URL 本地化

`getLocalizedUrl(string $url, ?string $locale = null): ?string`

获取提供 URL 和区域的本地化 URL。如果提供的 URL 是外部链接或未本地化，则返回 null。

示例

use \Alnaggar\Turjuman\Turjuman;

$spanishUrl = Turjuman::getLocalizedUrl('/about', 'es');

`getNonLocalizedUrl(string $url): ?string`

获取提供 URL 的非本地化 URL。如果提供的 URL 是外部链接，则返回 null。

示例

use \Alnaggar\Turjuman\Turjuman;

$originalUrl = Turjuman::getNonLocalizedUrl('/acerca-de');

本地化验证

`isLocalizedUrl(string $url, string $method = 'GET'): bool`

检查给定的 URL 是否在已注册的组中本地化。

示例

use \Alnaggar\Turjuman\Turjuman;

$isLocalizedUrl = Turjuman::isLocalizedUrl('/contact');

`isLocalizedRoute(\Illuminate\Routing\Route|string|null $route = null): bool`

检查提供的路由是否在已注册的组中本地化。如果传递 null，则执行当前路由的检查。

示例

use \Alnaggar\Turjuman\Turjuman;

$isLocalizedUrl = Turjuman::isLocalizedRoute('main.contact');

区域验证

`isSupportedLocale(string $locale): bool`

检查提供的区域是否在当前组中受支持。

示例

use \Alnaggar\Turjuman\Turjuman;

$isSupported = Turjuman::isSupportedLocale('es');

`isCurrentLocale(string $locale): bool`

检查提供的区域是否是当前区域。

示例

use \Alnaggar\Turjuman\Turjuman;

$isCurrent = Turjuman::isCurrentLocale('fr');

`isDefaultLocale(string $locale): bool`

检查提供的区域是否是默认区域。

示例

use \Alnaggar\Turjuman\Turjuman;

$isDefault = Turjuman::isDefaultLocale('en');

杂项

`getLocalesByProperty(string $property, mixed $default = null): string`

根据当前组支持的区域获取区域代码及其对应属性值的关联数组。

可选参数 $default 指定如果属性对于某个区域实例不存在时返回的值。如果传递闭包，则将区域实例作为参数提供。此函数对于获取当前定义组中每个受支持区域的特定信息或设置非常有用。它提供了灵活性，允许在请求的属性对于特定区域不可用的情况下指定默认值或行为。

示例

use \Alnaggar\Turjuman\Turjuman;

$localesCurrencies = Turjuman::getLocalesByProperty('currency', 'USD');

`getLocalizedPagePath(string $path, ?string $locale = null): string`

获取提供路径和区域的本地化页面路径。适用于 Laravel 视图和 Inertia 页面。

示例

use \Alnaggar\Turjuman\Turjuman;

$localizedPath = Turjuman::getLocalizedPagePath('contact', 'fr');

注意

在使用依赖于当前组或当前属性的函数之前，包含一个 if 语句以检查当前路由是否本地化是必不可少的。

辅助函数

可以使用 turjuman 辅助函数本地化 URL。

// Get the localized URL for a given path and locale
$url = turjuman('/about', 'ar');

贡献

如果您发现任何问题或有改进建议，请随时在 GitHub 仓库中打开问题或提交拉取请求。

致谢

巴勒斯坦横幅和徽章由 Safouene1 提供。

许可

Turjuman 是在 MIT 许可证下授权的开源软件。

alnaggar / turjuman

维护者

详细信息

README

目录

安装

配置

支持的本地化

默认本地化

在 URL 中显示本地化

隐藏默认本地化

路由别名

本地化标识符

中间件

SetLocale.php 中间件

LocalizeRoutes.php 中间件

功能

路由本地化

区域别名

本地化 URL 生成

分组属性

可扩展和可宏化

仅在需要时进行重定向

标准路由缓存

用法

路由分组

group(\Closure $routes, array $attributes = []): \Alnaggar\Turjuman\Group

ignore(\Illuminate\Routing\Route|\Closure $routes): void

配置管理

addConfigLocales(array $locales): \Alnaggar\Turjuman\Localizer

setConfigLocales(array $locales): \Alnaggar\Turjuman\Localizer

setConfigDefaultLocale(string $locale): \Alnaggar\Turjuman\Localizer

getConfigAttributes(): \Alnaggar\Turjuman\GroupAttributes

分组信息

getCurrentGroup(): ?\Alnaggar\Turjuman\Group

getCurrentAttributes(): \Alnaggar\Turjuman\GroupAttributes

区域管理

setCurrentLocale(string $locale): \Alnaggar\Turjuman\Locale

getLocale(string $locale): ?\Alnaggar\Turjuman\Locale

getSupportedLocales(): array

getDefaultLocale(): \Alnaggar\Turjuman\Locale

getCurrentLocale(): ?\Alnaggar\Turjuman\Locale