README

为 Laravel 提供简单易用的国际化（i18n）本地化，是一个与 Laravel 本地化类结合使用的有用工具。

本软件包提供以下功能

从浏览器检测语言
智能重定向（将区域设置保存在会话/cookie 中）
智能路由（只需定义一次路由，无论使用多少语言）
可翻译路由
支持缓存和测试
可以选择隐藏 URL 中的默认语言
许多代码片段和辅助工具（如语言选择器）

Laravel 兼容性

安装

通过 composer 安装包： composer require orbtall/laravel-localization

对于 Laravel 5.4 及以下版本，需要注册服务提供者。

配置文件

要编辑默认配置，您可以执行以下操作

php artisan vendor:publish --provider="Orbtall\LaravelLocalization\LaravelLocalizationServiceProvider"

之后，将创建 config/localization.php。

配置选项包括

supportedLocales 应用程序支持的语言（默认：英语和西班牙语）。
useAcceptLanguageHeader 如果为 true，则自动从浏览器检测语言。
hideDefaultLocaleInURL 如果为 true，则不在 URL 中显示默认语言。
localesOrder 按自定义顺序排序语言。
localesMapping 重命名 URL 区域设置。
utf8suffix 允许更改 CentOS 等的 utf8suffix。
urlsIgnored 忽略特定 URL。

注册中间件

您可以在 app/Http/Kernel.php 文件中注册软件包中间件

<?php namespace App\Http;

use Illuminate\Foundation\Http\Kernel as HttpKernel;

class Kernel extends HttpKernel {
    /**
    * The application's route middleware.
    *
    * @var array
    */
    protected $routeMiddleware = [
        /**** OTHER MIDDLEWARE ****/
        'localize'                => \Orbtall\LaravelLocalization\Middleware\LaravelLocalizationRoutes::class,
        'localizationRedirect'    => \Orbtall\LaravelLocalization\Middleware\LaravelLocalizationRedirectFilter::class,
        'localeSessionRedirect'   => \Orbtall\LaravelLocalization\Middleware\LocaleSessionRedirect::class,
        'localeCookieRedirect'    => \Orbtall\LaravelLocalization\Middleware\LocaleCookieRedirect::class,
        'localeViewPath'          => \Orbtall\LaravelLocalization\Middleware\LaravelLocalizationViewPath::class
    ];
}

使用

将以下内容添加到您的路由文件中

// routes/web.php

Route::group(['prefix' => LaravelLocalization::setLocale()], function()
{
	/** ADD ALL LOCALIZED ROUTES INSIDE THIS GROUP **/
	Route::get('/', function()
	{
		return View::make('hello');
	});

	Route::get('test',function(){
		return View::make('test');
	});
});

/** OTHER PAGES THAT SHOULD NOT BE LOCALIZED **/

一旦将此路由组添加到路由文件，用户就可以访问 supportedLocales 中添加的所有区域（默认为 us-en）。例如，上面的路由文件创建了以下地址

// Set application language to English
http://url-to-laravel/us-en
http://url-to-laravel/us-en/test

// Set application language to English or Spanish (depending on browsers default locales)
// if nothing found set to default locale
http://url-to-laravel
http://url-to-laravel/test

该软件包根据您的 URL 设置应用程序区域 App::getLocale()。然后可以使用此区域设置进行 Laravel 的本地化功能。

您可以使用以下方式向组添加中间件

Route::group(
[
	'prefix' => LaravelLocalization::setLocale(),
	'middleware' => [ 'localeSessionRedirect', 'localizationRedirect', 'localeViewPath' ]
], function(){ //...
});

建议

1.：强烈建议使用重定向中间件。不带区域的 URL 应仅用于确定浏览器/默认语言并重定向到本地化 URL。否则，当搜索引擎机器人爬取例如 http://url-to-laravel/test 时，他们可能会在每次访问时获得不同的语言内容。另外，为相同内容创建多个 URL 也会造成 SEO 重复内容问题。

2.：强烈建议本地化链接，即使您使用重定向中间件。否则，每次用户点击链接时至少会进行一次重定向。此外，来自帖子表单的任何操作 URL 都必须本地化，以防止它被重定向到 GET 请求。

重定向中间件

以下重定向中间件取决于 config/laravellocalization.php 中 hideDefaultLocaleInURL 和 useAcceptLanguageHeader 的设置

LocaleSessionRedirect

每当URL中存在区域设置时，此中间件将将其存储在会话中。

如果没有在URL中找到区域设置，那么此中间件将检查以下内容：

如果没有在会话中保存区域设置并且useAcceptLanguageHeader设置为true，则从浏览器中计算区域设置并将重定向到带有区域设置的URL。
如果会话中保存了区域设置，则重定向到带有区域设置的URL，除非它是默认区域设置且hideDefaultLocaleInURL设置为true。

例如，如果用户导航到http://url-to-laravel/test并且当前区域设置是en，它将自动将其重定向到http://url-to-laravel/en/test。

LocaleCookieRedirect

类似于LocaleSessionRedirect，但它将值存储在cookie中而不是会话中。

每当URL中存在区域设置时，此中间件将将其存储在cookie中。

如果没有在URL中找到区域设置，那么此中间件将检查以下内容：

如果没有在cookie中保存区域设置并且useAcceptLanguageHeader设置为true，则从浏览器中计算区域设置并将重定向到带有区域设置的URL。
如果在cookie中保存了区域设置，则重定向到带有区域设置的URL，除非它是默认区域设置且hideDefaultLocaleInURL设置为true。

例如，如果用户导航到http://url-to-laravel/test并且当前区域设置是de，它将自动将其重定向到http://url-to-laravel/de/test。

LaravelLocalizationRedirectFilter

当默认区域设置存在于URL中且hideDefaultLocaleInURL设置为true时，中间件将重定向到不带区域设置的URL。

例如，如果默认区域设置是es，那么http://url-to-laravel/es/test将被重定向到http://url-to-laravel/test，并且App::getLocale()将被设置为es。

辅助工具

此软件包附带了一组辅助函数。

本地化URL

在生成本地化路由时，考虑了本地化URL以及hideDefaultLocaleInURL和已翻译路由设置。

获取本地化URL

    // If current locale is Spanish, it returns `/es/test`
    <a href="{{ LaravelLocalization::localizeUrl('/test') }}">@lang('Follow this link')</a>

获取特定区域的本地化URL

获取特定区域的当前URL

// Returns current url with English locale.
{{ LaravelLocalization::getLocalizedURL('en') }}

获取干净的路线

返回任何本地化之外的URL。

// Returns /about
{{ LaravelLocalization::getNonLocalizedURL('/es/about') }}

获取特定翻译键的URL

返回一个路由，本地化到所需区域。如果翻译键在提供的区域中不存在，则此函数将返回false。

// Returns /es/acerca
{{ LaravelLocalization::getURLFromRouteNameTranslated('es', 'routes.about') }}

获取支持的区域设置

以数组形式返回所有支持的区域设置及其属性。

{{ LaravelLocalization::getSupportedLocales() }}

获取支持的区域设置自定义顺序

以配置文件中指定的顺序返回所有支持的区域设置。您可以使用此函数在语言选择器中打印区域设置。

{{ LaravelLocalization::getLocalesOrder() }}

获取支持的区域设置键

返回一个包含所有支持的区域设置键的数组。

{{ LaravelLocalization::getSupportedLanguagesKeys() }}

获取当前区域设置

返回当前区域设置的键。

{{ LaravelLocalization::getCurrentLocale() }}

获取当前区域设置名称

以字符串形式返回当前区域设置的名称（英语/西班牙语/阿拉伯语/等等）。

{{ LaravelLocalization::getCurrentLocaleName() }}

获取当前区域设置本地名称

以字符串形式返回当前区域设置的本地名称（英语/Español/عربى/等等）。

{{ LaravelLocalization::getCurrentLocaleNative() }}

获取当前区域设置方向

以字符串形式返回当前区域设置的方向（ltr/rtl）。

{{ LaravelLocalization::getCurrentLocaleDirection() }}

获取当前区域设置脚本

以字符串形式返回当前区域设置脚本的ISO 15924代码；“Latn”、“Cyrl”、“Arab”等。

{{ LaravelLocalization::getCurrentLocaleScript() }}

将视图基本路径设置为当前区域设置

注册中间件 LaravelLocalizationViewPath 以设置当前区域设置为视图基本路径。

现在您可以将视图包裹在基于语言的文件夹中，就像翻译文件一样。

resources/views/en/，resources/views/fr，...

映射自定义语言URL段

由于可以修改支持的区域设置（甚至可以通过更改它们的键来修改），因此可以使用字符串 uk 而不是 en-GB 来提供自定义语言URL段。当然，您需要防止与现有键发生冲突，并尽可能坚持约定。但是，如果您使用此类自定义键，则必须在 localesMapping 数组中存储您的映射。此 localesMapping 是启用语言协商器根据HTTP接受语言头正确分配所需区域设置所必需的。以下是一个将HTTP接受语言头 'en-GB' 映射到URL段 'uk' 的快速示例

// config/laravellocalization.php

'localesMapping' => [
	'en-GB' => 'uk'
],

之后，http://url-to-laravel/en-GB/a/b/c 变为 http://url-to-laravel/uk/a/b/c。

LaravelLocalization::getLocalizedURL('en-GB', 'a/b/c'); // http://url-to-laravel/uk/a/b/c
LaravelLocalization::getLocalizedURL('uk', 'a/b/c'); // http://url-to-laravel/uk/a/b/c

创建语言选择器

如果您正在支持您的项目中多个区域设置，您可能希望为用户提供更改语言的方法。以下是您可以用于创建自己的语言选择器的简单blade模板代码示例。

<ul>
    @foreach(LaravelLocalization::getSupportedLocales() as $localeCode => $properties)
        <li>
            <a rel="alternate" hreflang="{{ $localeCode }}" href="{{ LaravelLocalization::getLocalizedURL($localeCode, null, [], true) }}">
                {{ $properties['native'] }}
            </a>
        </li>
    @endforeach
</ul>

请注意，即使 hideDefaultLocaleInURL = true，默认语言也将强制在 getLocalizedURL() 中存在于URL中。

注意，支持路由模型绑定。

已翻译路由

您可以将路由翻译。例如，http://url/en/about 和 http://url/es/acerca（acerca是西班牙语的关于）或 http://url/en/article/important-article 和 http://url/es/articulo/important-article（article是西班牙语的 articulo）将重定向到以下相同的控制器/视图

必须在您的 Route::group 中加载 localize 中间件（请参阅安装说明）。

对于每种语言，在 resources/lang/**/routes.php 文件夹中添加一个 routes.php。该文件包含一个包含所有可翻译路由的数组。例如，如下所示

<?php
// resources/lang/en/routes.php
return [
    "about"    =>  "about",
    "article"  =>  "article/{article}",
];

<?php
// resources/lang/es/routes.php
return [
    "about"    =>  "acerca",
    "article"  =>  "articulo/{article}",
];

您可以将路由添加到 routes/web.php 中，如下所示

Route::group(['prefix' => LaravelLocalization::setLocale(),
              'middleware' => [ 'localize' ]], function () {

    Route::get(LaravelLocalization::transRoute('routes.about'), function () {
        return view('about');
    });

    Route::get(LaravelLocalization::transRoute('routes.article'), function (\App\Article $article) {
        return $article;
    });

    //,...
});

保存文件后，您可以无问题地访问 http://url/en/about，http://url/es/acerca，http://url/en/article/important-article 和 http://url/es/articulo/important-article。

可翻译路由参数

您可能在之前的示例中注意到西班牙语URL中的英文缩略语

http://url/es/articulo/important-article

可以有可翻译的缩略语，例如如下所示

http://url/en/article/important-change
http://url/es/articulo/cambio-importante

但是，为了做到这一点，每篇文章都必须有多个缩略语（每个区域设置一个）。您如何实现这种关系取决于您。对于可翻译路由参数的唯一要求是，相关的模型实现了接口 LocalizedUrlRoutable。

实现 LocalizedUrlRoutable

要实现 \Orbtall\LaravelLocalization\Interfaces\LocalizedUrlRoutable，必须创建函数 getLocalizedRouteKey($locale)，该函数必须返回给定区域设置的翻译缩略语。在上面的示例中，在文章模型内部，getLocalizedRouteKey('en') 应返回 important-change，而 getLocalizedRouteKey('es') 应返回 cambio-importante。

路由模型绑定

要使用 route-model-binding，应覆盖模型中的函数 resolveRouteBinding($slug)。该函数应返回属于翻译缩略语 $slug 的模型。例如

public function resolveRouteBinding($slug)
{
        return static::findByLocalizedSlug($slug)->first() ?? abort(404);
}

教程视频

您可以查看这个视频，该视频展示了如何设置可翻译的路由参数。

事件

如果您希望在翻译过程中捕获URL参数，可以这样做。只需创建一个对routes.translation事件的监听器，如下所示：

Event::listen('routes.translation', function($locale, $attributes)
{
	// Do your magic

	return $attributes;
});

请确保将地区和属性作为参数传递给闭包。您还可以使用事件订阅者，请参阅：https://laravel.net.cn/docs/events#event-subscribers

缓存路由

要缓存您的路由，请使用

php artisan route:trans:cache

...而不是正常的route:cache命令。使用artisan route:cache将不会正常工作！

要使路由缓存解决方案正常工作，需要对应用程序的路由配置进行微小调整。

在您的App的RouteServiceProvider中，使用LoadsTranslatedCachedRoutes特质

<?php
class RouteServiceProvider extends ServiceProvider
{
    use \Orbtall\LaravelLocalization\Traits\LoadsTranslatedCachedRoutes;

更多详情请参阅这里。

常见问题

POST 请求不工作

如果您没有在Routes::group内本地化动作路由，这可能会发生。这可能会导致重定向，进而将POST请求转换为GET请求。为防止这种情况，请简单地使用本地化助手。

例如，如果您使用Auth::routes()并将它们放入Route::group，则

<form action="/logout" method="POST">
<button>Logout</button>
</form>

将不会工作。相反，必须使用

<form action="{{  \LaravelLocalization::localizeURL('/logout') }} " method="POST">
<button>Logout</button>
</form>

另一种解决方法是，将HTTP方法配置到laravellocalization.httpMethodsIgnored中以防止处理此类请求

MethodNotAllowedHttpException

如果您没有本地化POST URL并使用重定向中间件，则POST请求将被重定向为GET请求。如果您没有定义此类GET路由，则会引发此异常。

有关如何本地化POST URL的示例，请参阅POST不工作。

验证消息仅在默认地区

如果您没有本地化POST URL，也会发生这种情况。如果您没有本地化POST URL，则在验证时设置默认地区，当使用back()返回时，会显示默认地区的验证消息。