alihan / laravel-localization
为Laravel提供的简单本地化
Requires
- php: >=7.1.0
- laravel/framework: ~5.2.0||~5.3.0||~5.4.0||~5.5.0||~5.6.0||~5.7.0||~5.8.0||^6.0||^7.0||^8.0||^9.0|^10.0
Requires (Dev)
- orchestra/testbench-browser-kit: ~3.4|~3.8|~4.0|^7.12
- phpunit/phpunit: 6.0.*|^8.0|^9.5.10
Suggests
- ext-intl: *
This package is not auto-updated.
Last update: 2024-09-26 18:42:35 UTC
README
为Laravel提供简单易用的i18n本地化工具,是一个与Laravel本地化类结合使用的有用工具。
此包提供以下功能
- 从浏览器检测语言
- 智能重定向(保存地区到会话/cookie中)
- 智能路由(只定义一次路由,无论使用多少种语言)
- 可翻译的路由
- 支持缓存和测试
- 选项:隐藏URL中的默认地区
- 许多代码片段和辅助工具(如语言选择器)
目录
Laravel兼容性
安装
通过composer安装此包: composer require mcamara/laravel-localization
对于Laravel 5.4及以下版本,需要注册服务提供者。
配置文件
为了编辑默认配置,您可以执行以下操作
php artisan vendor:publish --provider="Mcamara\LaravelLocalization\LaravelLocalizationServiceProvider"
之后,将创建config/laravellocalization.php
文件。
配置选项如下
- supportedLocales 应用程序支持的语言(默认:英语和西班牙语)。
- useAcceptLanguageHeader 如果为真,则自动从浏览器检测语言。
- hideDefaultLocaleInURL 如果为真,则不在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' => \Mcamara\LaravelLocalization\Middleware\LaravelLocalizationRoutes::class, 'localizationRedirect' => \Mcamara\LaravelLocalization\Middleware\LaravelLocalizationRedirectFilter::class, 'localeSessionRedirect' => \Mcamara\LaravelLocalization\Middleware\LocaleSessionRedirect::class, 'localeCookieRedirect' => \Mcamara\LaravelLocalization\Middleware\LocaleCookieRedirect::class, 'localeViewPath' => \Mcamara\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
中添加的所有地区(默认为en
和es
)。例如,上述路由文件创建了以下地址
// Set application language to English
http://url-to-laravel/en
http://url-to-laravel/en/test
// Set application language to Spanish
http://url-to-laravel/es
http://url-to-laravel/es/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
和 Translated Routes 设置。
获取本地化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
返回一个不包含任何本地化的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() }}
获取当前语言环境本地名称
以字符串形式返回当前语言环境的本地名称(英语/西班牙语/阿拉伯语/等等)。
{{ LaravelLocalization::getCurrentLocaleNative() }}
获取当前语言环境区域名称
以字符串形式返回当前区域名称(en_GB/en_US/fr_FR/等等)。
{{ LaravelLocalization::getCurrentLocaleRegional() }}
获取当前区域方向
以字符串形式返回当前区域的书写方向(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>
这里默认语言将在getLocalizedURL()中被强制显示在URL中,即使hideDefaultLocaleInURL = true
。
请注意,Route Model Binding被支持。
已翻译的路由
您可以翻译您的路由。例如,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
中间件(请参阅安装说明)。
对于每种语言,将routes.php
添加到resources/lang/**/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
要实现 \Mcamara\LaravelLocalization\Interfaces\LocalizedUrlRoutable
接口,需要创建一个名为 getLocalizedRouteKey($locale)
的函数,该函数必须返回给定语言的翻译后的缩略名。在上面的例子中,在文章模型内部,getLocalizedRouteKey('en')
应返回 important-change
,而 getLocalizedRouteKey('es')
应返回 cambio-importante
。
路由模型绑定
要使用 路由模型绑定,应该在模型中重写 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
将无法正确工作!
要使路由缓存解决方案正常工作,需要对您的应用程序路由配置进行少量调整。
在您的应用程序的 RouteServiceProvider
中,使用 LoadsTranslatedCachedRoutes
特性
<?php class RouteServiceProvider extends ServiceProvider { use \Mcamara\LaravelLocalization\Traits\LoadsTranslatedCachedRoutes;
有关更多详细信息,请参阅 这里。
常见问题
POST请求不工作
这可能发生在您没有对 Routes::group
内部的操作路由进行本地化。这可能导致重定向,进而将POST请求转换为GET请求。为防止这种情况,请简单使用 localize 辅助函数。
例如,如果您使用 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()
时,会显示默认语言的验证消息。
要本地化您的POST URL,请参阅 POST不工作 中的示例。
测试
在测试设置期间,所调用的路由尚未确定。这意味着无法设置任何语言。当在测试期间进行请求时,这将导致404 - 如果没有设置前缀,则看起来本地化路由不存在。
要修复此问题,您可以使用此函数手动设置语言前缀
// TestCase.php protected function refreshApplicationWithLocale($locale) { self::tearDown(); putenv(LaravelLocalization::ENV_ROUTE_KEY . '=' . $locale); self::setUp(); } protected function tearDown(): void { putenv(LaravelLocalization::ENV_ROUTE_KEY); parent::tearDown(); } // YourTest.php public function testBasicTest() { $this->refreshApplicationWithLocale('en'); // Testing code }
合作者
如果您想成为其中之一,请向 mcamara 咨询!
变更日志
在此处查看变更日志 -> changelog
许可
Laravel Localization 是一个开源的 Laravel 包,使用 MIT 许可证授权