跳到内容

本地化

简介

默认情况下,Laravel 应用程序骨架不包含 lang 目录。如果您想自定义 Laravel 的语言文件,您可以通 lang:publish Artisan 命令发布它们。

Laravel 的本地化功能提供了一种便捷的方式来检索各种语言的字符串,使您可以轻松地在应用程序中支持多种语言。

Laravel 提供了两种管理翻译字符串的方法。首先,语言字符串可以存储在应用程序 lang 目录中的文件中。在此目录中,可以为应用程序支持的每种语言设置子目录。这是 Laravel 用于管理内置 Laravel 功能(如验证错误消息)的翻译字符串的方法

1/lang
2 /en
3 messages.php
4 /es
5 messages.php

或者,翻译字符串可以定义在放置在 lang 目录中的 JSON 文件中。采用这种方法时,您的应用程序支持的每种语言都将在该目录中有一个对应的 JSON 文件。对于具有大量可翻译字符串的应用程序,建议使用这种方法

1/lang
2 en.json
3 es.json

我们将在本文档中讨论管理翻译字符串的每种方法。

发布语言文件

默认情况下,Laravel 应用程序骨架不包含 lang 目录。如果您想自定义 Laravel 的语言文件或创建自己的语言文件,则应通过 lang:publish Artisan 命令搭建 lang 目录。lang:publish 命令将在您的应用程序中创建 lang 目录,并发布 Laravel 使用的默认语言文件集

1php artisan lang:publish

配置区域设置

您的应用程序的默认语言存储在 config/app.php 配置文件的 locale 配置选项中,该选项通常使用 APP_LOCALE 环境变量设置。您可以自由修改此值以适应您的应用程序的需求。

您还可以配置“回退语言”,当默认语言不包含给定的翻译字符串时,将使用该语言。与默认语言一样,回退语言也在 config/app.php 配置文件中配置,其值通常使用 APP_FALLBACK_LOCALE 环境变量设置。

您可以使用 App 外观模式提供的 setLocale 方法在运行时修改单个 HTTP 请求的默认语言

1use Illuminate\Support\Facades\App;
2 
3Route::get('/greeting/{locale}', function (string $locale) {
4 if (! in_array($locale, ['en', 'es', 'fr'])) {
5 abort(400);
6 }
7 
8 App::setLocale($locale);
9 
10 // ...
11});

确定当前区域设置

您可以使用 App 外观模式上的 currentLocaleisLocale 方法来确定当前区域设置或检查区域设置是否为给定值

1use Illuminate\Support\Facades\App;
2 
3$locale = App::currentLocale();
4 
5if (App::isLocale('en')) {
6 // ...
7}

复数语言

您可以指示 Laravel 的“复数化器”(Eloquent 和框架的其他部分使用它来将单数字符串转换为复数字符串)使用英语以外的语言。这可以通过在应用程序的服务提供者的 boot 方法中调用 useLanguage 方法来完成。复数化器当前支持的语言有:frenchnorwegian-bokmalportuguesespanishturkish

1use Illuminate\Support\Pluralizer;
2 
3/**
4 * Bootstrap any application services.
5 */
6public function boot(): void
7{
8 Pluralizer::useLanguage('spanish');
9 
10 // ...
11}

如果您自定义复数化器的语言,则应显式定义 Eloquent 模型的 表名

定义翻译字符串

使用短键

通常,翻译字符串存储在 lang 目录中的文件中。在此目录中,应为应用程序支持的每种语言设置一个子目录。这是 Laravel 用于管理内置 Laravel 功能(如验证错误消息)的翻译字符串的方法

1/lang
2 /en
3 messages.php
4 /es
5 messages.php

所有语言文件都返回一个键控字符串数组。例如

1<?php
2 
3// lang/en/messages.php
4 
5return [
6 'welcome' => 'Welcome to our application!',
7];

对于因地区而异的语言,您应根据 ISO 15897 命名语言目录。例如,英国英语应使用 "en_GB" 而不是 "en-gb"。

使用翻译字符串作为键

对于具有大量可翻译字符串的应用程序,当在视图中引用键时,使用“短键”定义每个字符串可能会变得令人困惑,并且为应用程序支持的每个翻译字符串不断发明键也很麻烦。

因此,Laravel 还支持使用字符串的“默认”翻译作为键来定义翻译字符串。使用翻译字符串作为键的语言文件以 JSON 文件形式存储在 lang 目录中。例如,如果您的应用程序有西班牙语翻译,则应创建一个 lang/es.json 文件

1{
2 "I love programming.": "Me encanta programar."
3}

键 / 文件冲突

您不应定义与其他翻译文件名冲突的翻译字符串键。例如,为 "NL" 区域设置翻译 __('Action'),同时存在 nl/action.php 文件,但不存在 nl.json 文件,将导致翻译器返回 nl/action.php 的全部内容。

检索翻译字符串

您可以使用 __ 助手函数从语言文件中检索翻译字符串。如果您使用“短键”来定义翻译字符串,则应使用“点”语法将包含键的文件和键本身传递给 __ 函数。例如,让我们从 lang/en/messages.php 语言文件中检索 welcome 翻译字符串

1echo __('messages.welcome');

如果指定的翻译字符串不存在,则 __ 函数将返回翻译字符串键。因此,使用上面的示例,如果翻译字符串不存在,则 __ 函数将返回 messages.welcome

如果您使用 默认翻译字符串作为翻译键,则应将字符串的默认翻译传递给 __ 函数;

1echo __('I love programming.');

同样,如果翻译字符串不存在,则 __ 函数将返回给定的翻译字符串键。

如果您使用 Blade 模板引擎,则可以使用 {{ }} 回显语法来显示翻译字符串

1{{ __('messages.welcome') }}

替换翻译字符串中的参数

如果需要,您可以在翻译字符串中定义占位符。所有占位符都以 : 为前缀。例如,您可以定义带有占位符名称的欢迎消息

1'welcome' => 'Welcome, :name',

要在检索翻译字符串时替换占位符,您可以将替换数组作为第二个参数传递给 __ 函数

1echo __('messages.welcome', ['name' => 'dayle']);

如果您的占位符包含所有大写字母,或者仅首字母大写,则翻译后的值将相应地大写

1'welcome' => 'Welcome, :NAME', // Welcome, DAYLE
2'goodbye' => 'Goodbye, :Name', // Goodbye, Dayle

对象替换格式

如果您尝试提供对象作为翻译占位符,则将调用该对象的 __toString 方法。__toString 方法是 PHP 内置的“魔术方法”之一。但是,有时您可能无法控制给定类的 __toString 方法,例如,当您与之交互的类属于第三方库时。

在这些情况下,Laravel 允许您为该特定类型的对象注册自定义格式处理程序。要完成此操作,您应调用翻译器的 stringable 方法。stringable 方法接受一个闭包,该闭包应类型提示它负责格式化的对象类型。通常,应在应用程序 AppServiceProvider 类的 boot 方法中调用 stringable 方法

1use Illuminate\Support\Facades\Lang;
2use Money\Money;
3 
4/**
5 * Bootstrap any application services.
6 */
7public function boot(): void
8{
9 Lang::stringable(function (Money $money) {
10 return $money->formatTo('en_GB');
11 });
12}

复数

复数是一个复杂的问题,因为不同的语言对于复数有各种复杂的规则;但是,Laravel 可以帮助您根据您定义的复数规则以不同的方式翻译字符串。使用 | 字符,您可以区分字符串的单数和复数形式

1'apples' => 'There is one apple|There are many apples',

当然,使用 翻译字符串作为键 时也支持复数

1{
2 "There is one apple|There are many apples": "Hay una manzana|Hay muchas manzanas"
3}

您甚至可以创建更复杂的复数规则,这些规则指定多个值范围的翻译字符串

1'apples' => '{0} There are none|[1,19] There are some|[20,*] There are many',

定义具有复数选项的翻译字符串后,您可以使用 trans_choice 函数检索给定“计数”的行。在此示例中,由于计数大于 1,因此返回翻译字符串的复数形式

1echo trans_choice('messages.apples', 10);

您还可以在复数字符串中定义占位符属性。可以通过将数组作为第三个参数传递给 trans_choice 函数来替换这些占位符

1'minutes_ago' => '{1} :value minute ago|[2,*] :value minutes ago',
2 
3echo trans_choice('time.minutes_ago', 5, ['value' => 5]);

如果您想显示传递给 trans_choice 函数的整数值,您可以使用内置的 :count 占位符

1'apples' => '{0} There are none|{1} There is one|[2,*] There are :count',

覆盖软件包语言文件

一些软件包可能自带语言文件。您不必更改软件包的核心文件来调整这些行,而是可以通过将文件放在 lang/vendor/{package}/{locale} 目录中来覆盖它们。

例如,如果您需要覆盖名为 skyrim/hearthfire 的软件包中 messages.php 文件中的英文翻译字符串,则应将语言文件放在:lang/vendor/hearthfire/en/messages.php。在此文件中,您应该仅定义您希望覆盖的翻译字符串。您未覆盖的任何翻译字符串仍将从软件包的原始语言文件中加载。

Laravel 是最高效的
构建、部署和监控软件的方式。