本地化

未匹配的标注
本文档最新版为 10.x,旧版本可能放弃维护,推荐阅读最新版!

本地化

介绍

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

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

Laravel 提供两种管理翻译字符串的方式。第一种,语言字符串可以存储在应用程序的 lang 目录中的文件里。在这个目录中,可能会为应用程序支持的每种语言创建子目录。这是 Laravel 用于管理内置功能(如验证错误消息)的翻译字符串的方法:

/lang
    /en
        messages.php
    /es
        messages.php

第二种,翻译字符串可以定义在放置在 lang 目录中的 JSON 文件中。采用这种方法时,您的应用程序支持的每种语言都会在这个目录中有一个对应的 JSON 文件。这种方法适用于具有大量翻译字符串需求的应用程序:

/lang
    en.json
    es.json

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

发布语言文件

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

php artisan lang:publish

配置区域

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

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

您可以在运行时使用 App 门面(Facade)提供的 setLocale 方法修改单个 HTTP 请求的默认语言:

use Illuminate\Support\Facades\App;

Route::get('/greeting/{locale}', function (string $locale) {
    if (! in_array($locale, ['en', 'es', 'fr'])) {
        abort(400);
    }

    App::setLocale($locale);

    // ...
});

确定当前语言环境

您可以使用 App 门面(Facade)上的 currentLocaleisLocale 方法来确定当前语言环境或检查语言环境是否为指定的值:

use Illuminate\Support\Facades\App;

$locale = App::currentLocale();

if (App::isLocale('en')) {
    // ...
}

多语言

您可以指示 Laravel 的 「复数化器(pluralizer)」(由 Eloquent 和框架的其他部分使用,将单数字符串转换为复数字符串)使用英语以外的语言。这可以通过在应用程序的某个服务提供者的 boot 方法中调用 useLanguage 方法来实现。复数化器当前支持的语言有:french(法语)norwegian-bokmal(挪威语-博克马尔语)portuguese(葡萄牙语)spanish(西班牙语)turkish(土耳其语)

use Illuminate\Support\Pluralizer;

/**
 * 引导所有应用服务.
 */
public function boot(): void
{
    Pluralizer::useLanguage('spanish');     

    // ...     
}

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

定义翻译字符串

使用短键

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

/lang
    /en
        messages.php
    /es
        messages.php

所有语言文件返回一个键值对字符串数组。例如:

<?php

// lang/en/messages.php

return [
    'welcome' => 'Welcome to our application!',
];

[!WARNING]
对于按地区不同的语言,应根据 ISO 15897 的命名规范命名语言目录。例如,应该使用 「en_GB」 表示英国英语,而不是 「en-gb」。

使用翻译字符串作为键

对于有大量需翻译字符串的应用,为每个字符串定义一个「短键」并在视图中引用这些键时,可能会变得非常混乱,而且不断为应用支持的每个翻译字符串增加新的键会日益繁琐。

因此,Laravel 还支持使用字符串的「默认(default)」翻译作为键来定义翻译字符串。我们可以将使用翻译字符串作为键的语言文件存储为 JSON 文件,并存放在 lang 目录中,以此实现这样的功能。例如,如果您的应用有一个西班牙语翻译,您应该创建一个 lang/es.json 文件:

{
    "I love programming.": "Me encanta programar."
}

键 / 文件 冲突问题

您不应该定义与其他翻译文件名冲突的翻译字符串键。例如,在存在 nl/action.php 文件但不存在 nl.json 文件的情况下,为「NL」语言环境翻译 __('Action') ,这将导致翻译器返回 nl/action.php 文件的整个内容。

检索翻译字符串

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

echo __('messages.welcome');

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

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

echo __('I love programming.');

再次强调,如果翻译字符串不存在,__ 函数将返回它所接收到的翻译字符串键。

如果您正在使用 Blade模板引擎 ,您可以使用 {{ }} 输出语法来显示翻译字符串:

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

在翻译字符串中替换参数

您可以根据需要在翻译字符串中定义占位符。所有的占位符都以 : 开头。例如,您可以定义一个带有占位符名称的欢迎消息:

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

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

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

如果您的占位符全部是大写字母,或者只有第一个字母是大写的,翻译后的值将会相应地保持首字母大写:

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

对象替换格式

如果尝试将对象作为翻译占位符,将会调用对象的 __toString 方法。__toString 方法是 PHP 内置的「魔术方法」之一。然而,有时您可能无法控制给定类的 __toString 方法,特别是当您与属于第三方库的类进行交互时。

在这些情况下,Laravel 允许您为特定类型的对象注册自定义格式化处理程序。要实现这一点,您可以调用翻译器的 stringable 方法。stringable 方法接受一个闭包,该闭包应该对其所负责格式化的对象类型进行类型提示。通常,stringable 方法在您应用的 AppServiceProvider 类的 boot 方法中调用:

use Illuminate\Support\Facades\Lang;
use Money\Money;

/**
 * 引导所有应用服务
 */
public function boot(): void
{
    Lang::stringable(function (Money $money) {
        return $money->formatTo('en_GB');
    });
}

复数化

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

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

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

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

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

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

在定义具有复数化选项的翻译字符串后,您可以使用 trans_choice 函数根据给定的「数量(count)」来检索行。在本例中,由于计数大于一,所以返回翻译字符串的复数形式:

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

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

'minutes_ago' => '{1} :value minute ago|[2,*] :value minutes ago',

echo trans_choice('time.minutes_ago', 5, ['value' => 5]);

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

'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。在这个文件中,您只需定义您希望重写的翻译字符串。任何您没有重写的翻译字符串仍将从包的原始语言文件中加载。

本文章首发在 LearnKu.com 网站上。

本译文仅用于学习和交流目的,转载请务必注明文章译者、出处、和本文链接
我们的翻译工作遵照 CC 协议,如果我们的工作有侵犯到您的权益,请及时联系我们。

原文地址:https://learnku.com/docs/laravel/11.x/lo...

译文地址:https://learnku.com/docs/laravel/11.x/lo...

上一篇 下一篇
《L04 微信小程序从零到发布》
从小程序个人账户申请开始,带你一步步进行开发一个微信小程序,直到提交微信控制台上线发布。
《L02 从零构建论坛系统》
以构建论坛项目 LaraBBS 为线索,展开对 Laravel 框架的全面学习。应用程序架构思路贴近 Laravel 框架的设计哲学。
贡献者:2
讨论数量: 0
发起讨论 只看当前版本


暂无话题~