CodeIgniter 4 本地化(Localization)完全指南:从 Locale 配置到语言文件自动化生成

原创2026-10-11 16:02:561,741 阅读
文章标签:后端Web框架

CodeIgniter 4 本地化(Localization)完全指南:从 Locale 配置到语言文件自动化生成

本指南围绕 CodeIgniter 4 的本地化体系展开,覆盖 Locale 的默认值与自动检测、语言文件(Language Files)的编写与读取、基于 intl 扩展的参数替换与多语言格式化、以及 lang:find / lang:sync 两个 CLI 命令的自动化翻译管理。读完你将能独立为 CodeIgniter 4 应用配置多语言环境,并借助框架源码理解每个配置项与命令背后的真实工作链路。

一、Locale 基础:理解语言/地区代码

CodeIgniter 4 将"本地化"拆成两层:Locale(当前站点运行的语言/地区环境)与 Language(具体语言字符串的存放与读取)。一个 Locale 大体上代表访问者使用的语言和地区组合,它不仅影响语言字符串,还影响货币符号、数字格式等格式化行为(参见 app/Config/App.php 中 defaultLocale 的注释说明)。

框架推荐使用 BCP 47 语言标签,例如美式英语用 en-US、法国法语用 fr-FR。可读性更好的介绍可参考 W3C 的 Language tags in HTML 文档。

Locale 的取值可以是你的应用用于管理文本字符串和格式的任何字符串,但使用标准语言代码可以让你直接受益于框架内置的语言回退机制(详见后文"Language Fallback")。

二、配置默认 Locale

每个站点都有一个默认语言/地区。默认值在 app/Config/App.php 中通过 $defaultLocale 属性设置:

<?php

namespace Config;

use CodeIgniter\Config\BaseConfig;

class App extends BaseConfig
{
    // ...

    public string $defaultLocale = 'en';

    // ...
}

仓库中默认配置为 'en'(见 app/Config/App.php)。从源码看(system/HTTP/IncomingRequest.php),IncomingRequest::detectLocale() 会先把 locale 与 defaultLocale 都初始化为 $config->defaultLocale,再按需进入自动检测流程,因此默认 Locale 是整条检测链的兜底值。

语言回退的智能性:系统足够聪明,在找不到精确匹配时会回退到更通用的语言代码。例如 Locale 设置为 en-US,但你的语言文件目录只有 en,那么 en 目录下的文件会被使用;反之,如果存在 app/Language/en-US 目录,则会优先使用它。

三、Locale 自动检测

重要:Locale 检测只对基于 Web 的、使用 IncomingRequest 类的请求生效,命令行(CLI)请求不具备这些特性。

框架在请求周期内支持两种 Locale 检测方式:

  1. 内容协商(Content Negotiation):一种"设置后即忘"(set and forget)的方法,自动执行内容协商来决定正确的 Locale。
  2. 路由内检测(In Routes):在路由中指定一个 URL 片段来设置 Locale。

如果需要在运行时直接设置 Locale,请参考下文"设置当前 Locale"一节。

另外,自 v4.4.0 起新增了 IncomingRequest::setValidLocales() 方法,用于动态设置(及重置)从 Config\App::$supportedLocales 初始化而来的合法 Locale 列表。对应实现见 system/HTTP/IncomingRequest.php。

3.1 内容协商(Content Negotiation)

在 app/Config/App.php 中设置两个附加配置即可开启自动内容协商。第一个开关告诉 Request 类我们确实需要协商 Locale,设为 true 即可:

<?php

namespace Config;

use CodeIgniter\Config\BaseConfig;

class App extends BaseConfig
{
    // ...

    public bool $negotiateLocale = true;

    // ...
}

注意:仓库默认值为 false(app/Config/App.php),需要按需开启。

开启后,系统会根据你在 $supportedLocales 中定义的 Locale 数组,自动协商正确的语言。协商依据的是请求头中的 Accept-Language 字段(system/HTTP/Negotiate.php)。如果客户端请求的语言与你支持的语言没有任何匹配,则使用 $supportedLocales 中的第一项。例如下面的配置中,无匹配时将使用 en:

<?php

namespace Config;

use CodeIgniter\Config\BaseConfig;

class App extends BaseConfig
{
    // ...

    public array $supportedLocales = ['en', 'es', 'fr-FR'];

    // ...
}

从源码链路看:IncomingRequest::detectLocale() 在 $config->negotiateLocale 为真时,会调用 $this->negotiate('language', $config->supportedLocales) 并把协商结果交给 setLocale()(system/HTTP/IncomingRequest.php)。底层 Negotiate::language() 还会参考 Feature 配置中的 strictLocaleNegotiation:开启后执行严格匹配(getBestLocaleMatch),关闭时则允许把 fr-FR 这类子地区匹配到 fr 这类宽泛类型($matchLocales 参数为 true,见 system/HTTP/Negotiate.php)。

3.2 路由内检测(In Routes)

第二种方式使用自定义占位符来检测期望的 Locale 并把它设置到 Request 上。占位符 {locale} 可以作为路由中的一段 URL 片段;如果出现,匹配该片段的内容就是你的 Locale:

$routes->get('{locale}/books', 'App\Books::index');

在这个例子中,如果用户访问 **http://example.com/fr/books**,那么 Locale 会被设置为 fr(前提是 fr 已配置为合法 Locale)。

如果该值没有匹配 app/Config/App.php 中 $supportedLocales 定义的任何合法 Locale,将改用默认 Locale;除非你设置只使用 App 配置文件中定义的受支持 Locale:

$routes->useSupportedLocalesOnly(true);

注意:useSupportedLocalesOnly() 自 v4.3.0 起可用。

源码佐证:RouteCollection 中维护了一个 useSupportedLocalesOnly 标志(system/Router/RouteCollection.php),提供对应的设置/读取方法(system/Router/RouteCollection.php)。路由替换逻辑位于 replaceLocale():当路由含 {locale} 时,若该段值不在 $config->supportedLocales 中则置空并回退为当前请求的 Locale(system/Router/RouteCollection.php),最终由 replaceLocaleTag() 用 service('request')->getLocale() 填充(system/Router/RouteCollection.php)。

四、设置当前 Locale

4.1 通过 IncomingRequest 设置

如果想直接设置 Locale,可以使用 IncomingRequest 的 setLocale() 方法:

/** @var \CodeIgniter\HTTP\IncomingRequest $request */
$request->setLocale('ja');

在调用 setLocale() 之前,必须先设置好合法 Locale 列表——因为任何设置为不合法 Locale 的尝试都会导致回退到默认 Locale。默认情况下,合法 Locale 由 app/Config/App.php 中的 Config\App::$supportedLocales 定义:

public array $supportedLocales = ['en', 'es', 'fr-FR'];

源码确认:setLocale() 首先用 in_array($locale, $this->validLocales, true) 做严格校验,不合法则赋值为 defaultLocale;随后调用 PHP 的 Locale::setDefault($locale) 同步全局 Locale(system/HTTP/IncomingRequest.php)。注意 supportedLocales 数组在请求构造时被复制到 $this->validLocales(system/HTTP/IncomingRequest.php),因此 v4.4.0 新增的 setValidLocales() 可以脱离配置文件在运行时动态替换这个白名单。

4.2 通过 Language 类设置

lang() 函数所使用的 Language 类也持有当前 Locale,它会在实例化时被设置为 IncomingRequest 的 Locale(即 language 服务创建时会以请求 Locale 作为构造参数,见 system/Language/Language.php)。

如果需要在 Language 类实例化之后修改 Locale,使用 Language::setLocale() 方法:

/** @var \CodeIgniter\Language\Language $lang */
$lang = service('language');
$lang->setLocale('ja');

Language::setLocale() 的实现会直接替换内部 $locale 属性并返回 $this 以支持链式调用(system/Language/Language.php)。

五、获取当前 Locale

当前 Locale 始终可以通过 IncomingRequest 对象的 getLocale() 方法获取。如果你的控制器继承自 CodeIgniter\Controller,可以通过 $this->request 访问:

<?php

namespace App\Controllers;

class UserController extends BaseController
{
    public function index()
    {
        $locale = $this->request->getLocale();
    }
}

也可以使用 Services 类获取当前请求:

$locale = service('request')->getLocale();

getLocale() 直接返回内部 $locale 属性;另有 getDefaultLocale() 返回配置中的默认值(system/HTTP/IncomingRequest.php)。

六、创建语言文件(Language Files)

语言字符串存放在 app/Language 目录中,每种受支持的语言(Locale)对应一个子目录:

app/
    Language/
        en/
            App.php
        fr/
            App.php

注意:语言文件没有命名空间。

语言文件没有强制的命名约定,文件名应当能逻辑地描述其内容类型。例如你想创建一个存放错误信息的文件,可以直接命名为 Errors.php。

文件内容是一个返回数组的 PHP 文件,数组每个元素是一个语言键(language key)与对应的字符串:

<?php

return [
    'languageKey' => 'The actual message to be shown.',
];

注意:语言键的开头和结尾不能使用点号(.)。

它也支持嵌套定义:

return [
    'languageKey' => [
        'nested' => [
            'key' => 'The actual message to be shown.',
        ],
    ],
];

下面是一个更完整的示例文件(Errors.php),同时包含普通键与嵌套键:

<?php

return [
    'errorEmailMissing'    => 'You must submit an email address',
    'errorURLMissing'      => 'You must submit a URL',
    'errorUsernameMissing' => 'You must submit a username',
    'nested'               => [
        'error' => [
            'message' => 'A specific error message',
        ],
    ],
];

七、基本用法:lang() 函数

可以使用 lang() 辅助函数从任意语言文件中获取文本,第一个参数传入"文件名.语言键",用点号(.)分隔。

例如,加载 Errors.php 语言文件中的 errorEmailMissing 字符串:

echo lang('Errors.errorEmailMissing');

嵌套定义的读取方式:

echo lang('Errors.nested.error.message');

如果请求的语言键在当前 Locale 的文件中不存在(经过 Language Fallback 之后仍找不到),字符串会原样返回。在上面的例子中,若键不存在,将分别返回 Errors.errorEmailMissing 或 Errors.nested.error.message。

从源码看,lang() 定义于 system/Common.php:它通过 service('language') 拿到共享的 Language 实例,先记录当前活动 Locale;若第三个参数 $locale 非空且不同于活动 Locale,则临时切换、调用 getLine() 后再恢复原 Locale。Language::getLine() 则执行完整的"当前 Locale → 去掉地区后缀的 Locale(如 en-US → en)→ 英文 en → 原样返回"的五级解析(system/Language/Language.php)。

八、参数替换与 ICU 格式化

注意:以下函数全部依赖系统的 intl 扩展才能工作;如果该扩展未加载,将不会执行任何替换。

你可以把一组值作为 lang() 的第二个参数传入,替换语言字符串中的占位符,这允许非常简单的数字翻译与格式化。以下面的语言文件 Tests.php 为例:

<?php

// The language file, Tests.php:
return [
    'apples'      => 'I have {0, number} apples.',
    'men'         => 'The top {1, number} men out-performed the remaining {0, number}',
    'namedApples' => 'I have {number_apples, number, integer} apples.',
];

// Displays "I have 3 apples."
echo lang('Tests.apples', [3]);

占位符中的第一项对应数组中的索引(如果是数字索引):

// Displays "The top 23 men out-performed the remaining 20"
echo lang('Tests.men', [20, 23]);

也可以使用命名键让对应关系更清晰:

// Displays "I have 3 apples."
echo lang('Tests.namedApples', ['number_apples' => 3]);

当然,能做的远不止数字替换。根据底层 ICU 库 MessageFormat 的官方文档,以下数据类型都可以被替换:

  • numbers —— 整数、货币、百分比(integer, currency, percent)
  • dates —— 短、中、长、完整(short, medium, long, full)
  • time —— 短、中、长、完整(short, medium, long, full)
  • spellout —— 拼写出数字(如 34 → thirty-four)
  • ordinal —— 序数
  • duration —— 时长

以下是一组示例:

<?php

// The language file, Tests.php
return [
    'shortTime'  => 'The time is now {0, time, short}.',
    'mediumTime' => 'The time is now {0, time, medium}.',
    'longTime'   => 'The time is now {0, time, long}.',
    'fullTime'   => 'The time is now {0, time, full}.',
    'shortDate'  => 'The date is now {0, date, short}.',
    'mediumDate' => 'The date is now {0, date, medium}.',
    'longDate'   => 'The date is now {0, date, long}.',
    'fullDate'   => 'The date is now {0, date, full}.',
    'spelledOut' => '34 is {0, spellout}',
    'ordinal'    => 'The ordinal is {0, ordinal}',
    'duration'   => 'It has been {0, duration}',
];

// Displays "The time is now 11:18 PM"
echo lang('Tests.shortTime', [time()]);
// Displays "The time is now 11:18:50 PM"
echo lang('Tests.mediumTime', [time()]);
// Displays "The time is now 11:19:09 PM CDT"
echo lang('Tests.longTime', [time()]);
// Displays "The time is now 11:19:26 PM Central Daylight Time"
echo lang('Tests.fullTime', [time()]);

// Displays "The date is now 8/14/16"
echo lang('Tests.shortDate', [time()]);
// Displays "The date is now Aug 14, 2016"
echo lang('Tests.mediumDate', [time()]);
// Displays "The date is now August 14, 2016"
echo lang('Tests.longDate', [time()]);
// Displays "The date is now Sunday, August 14, 2016"
echo lang('Tests.fullDate', [time()]);

// Displays "34 is thirty-four"
echo lang('Tests.spelledOut', [34]);

// Displays "It has been 408,676:24:35"
echo lang('Tests.ordinal', [time()]);

上例中 spelledOut 需要 spellout 类型、ordinal 输出的是时长示例,请以实际 intl 数据为准。建议系统阅读 MessageFormatter 类及底层 ICU 格式化的能力(条件替换、复数等)。

底层实现上,Language::formatMessage() 检查 intlSupport(构造时通过 class_exists(MessageFormatter::class) 探测)且参数非空时,调用 MessageFormatter::formatMessage($this->locale, $message, $args);若格式化返回 false,会记录错误日志并返回原始字符串加警告后缀(system/Language/Language.php)。

8.1 指定不同 Locale 进行替换

想在替换参数时使用另一个 Locale,可以把 Locale 作为第三个参数传给 lang():

// Displays "The time is now 23:21:28 GMT-5"
echo lang('Test.longTime', [time()], 'ru-RU');

// Displays "£7.41"
echo lang('{price, number, currency}', ['price' => 7.41], 'en-GB');
// Displays "$7.41"
echo lang('{price, number, currency}', ['price' => 7.41], 'en-US');

注意最后一个例子直接把整条格式化模板作为"行"传入——因为 getLine() 对不含点号的字符串会原样交给 formatMessage() 处理(system/Language/Language.php),因此可以绕过语言文件直接使用 ICU 模板做货币、数字格式化。

8.2 嵌套数组

语言文件还允许嵌套数组,便于处理列表等场景:

<?php

// Language/en/Fruit.php

return [
    'list' => [
        'Apples',
        'Bananas',
        'Grapes',
        'Lemons',
        'Oranges',
        'Strawberries',
    ],
];

// Displays "Apples, Bananas, Grapes, Lemons, Oranges, Strawberries"
echo implode(', ', lang('Fruit.list'));

九、Language Fallback(语言回退)

如果你有一套特定 Locale 的消息,例如 Language/en/App.php,可以为该 Locale 添加变体,每个变体放在独立目录,例如 Language/en-US/App.php。

你只需要为那些在该 Locale 变体中确实需要不同翻译的消息提供值,任何缺失的消息定义会自动从主 Locale 设置中获取。

更好的是——本地化可以一路回退到英文(en):当框架新增了消息而你还未来得及为你的 Locale 翻译时,就会用到这个机制。

因此,如果你使用 Locale fr-CA,一条本地化消息会依次在 Language/fr-CA 目录、Language/fr 目录、最后在 Language/en 目录中查找。

源码验证:Language::getLine() 的步骤 3 与步骤 4 正是这个"地区回退 + 英文兜底"逻辑——当当前 Locale 含 - 时,先 explode('-', $this->locale, 2) 取基础语言再查一次,仍为空则以 en 兜底(system/Language/Language.php)。而文件加载(requireFile)通过 service('locator')->search() 在多个命名空间(框架、包、应用)中查找同一路径的语言文件并递归合并(system/Language/Language.php),这正是应用覆盖系统消息的机制基础。

十、系统消息翻译(System Message Translations)

CodeIgniter 4 框架自身(如验证错误、异常信息等)有一套"官方"的系统消息翻译集合,存放在独立的 translations 仓库中。两种集成方式:

方式一:手动复制。下载该仓库,把其中的 Language 文件夹复制到你的 app 文件夹中。由于 App 命名空间映射到你的 app 文件夹,这些翻译会被自动拾取。

方式二(推荐):Composer 安装。在你的项目内执行:

composer require codeigniter4/translations

安装后,翻译文件夹会被正确映射,翻译消息自动生效。

框架自身的英文系统消息位于 system/Language/en,例如 system/Language/en/Validation.php、system/Language/en/Errors.php 等,可作为对照参考。

十一、覆盖系统消息翻译

框架提供系统消息翻译,你安装的第三方包也可能提供消息翻译。

如果想覆盖某些语言消息,只需在 app/Language 目录创建语言文件,并在文件中只返回你想覆盖的那部分数组即可。得益于 requireFile() 的 array_replace_recursive 合并逻辑(system/Language/Language.php),应用目录中的同名文件会递归覆盖框架与包提供的同键消息,而不会影响其他键。

十二、使用 CLI 命令生成翻译文件(lang:find)

自 v4.5.0 起可用。命令实现位于 system/Commands/Translation/LocalizationFinder.php,对应的测试见 tests/system/Commands/Translation/LocalizationFinderTest.php。

你可以自动生成和更新 app 目录中的翻译文件。该命令会搜索代码中 lang() 函数的使用情况,并结合 app/Language 中已有的翻译键,以 Config\App 的 defaultLocale 作为写入 Locale 来生成/更新语言文件。操作完成后,需要你自己翻译这些语言键。

命令能够正常识别嵌套键,例如 File.array.nested.text 这种形式。之前已保存的键不会被改变。

注意:lang() 已经能够解析的键(例如来自 system/Language 的 Errors.*)被视为"已翻译",因此既不会被 --show-new 列出,也不会被写入 app/Language。

基本用法:

php spark lang:find

下面是命令生成的示例文件(以 lang() 调用为键名、键路径为占位值):

// Controllers/Translation/Lang.php
$message  = lang('Text.info.success');
$message2 = lang('Text.paragraph');

// The following will be saved in Language/en/Text.php
return [
    'info' => [
        'success' => 'Text.info.success',
    ],
    'paragraph' => 'Text.paragraph',
];

注意:命令扫描文件夹时会跳过 app/Language 目录(源码 isIgnoredFile() 会排除语言目录自身,见 system/Commands/Translation/LocalizationFinder.php),避免把已生成的翻译当作新键再次处理。

生成的翻译文件很可能不符合你的编码规范,建议进行格式化。例如,如果安装了 php-cs-fixer,可以执行:

vendor/bin/php-cs-fixer fix ./app/Language

更新之前,可以预览命令找到的翻译:

php spark lang:find --verbose --show-new

--verbose 的详细输出还会展示无效键(Bad Keys)列表。例如:

...

Files found: 10
New translates found: 30
Bad translates found: 5
+------------------------+---------------------------------+
| Bad Key                | Filepath                        |
+------------------------+---------------------------------+
| ..invalid_nested_key.. | app/Controllers/Translation.php |
| .invalid_key           | app/Controllers/Translation.php |
| TranslationBad         | app/Controllers/Translation.php |
| TranslationBad.        | app/Controllers/Translation.php |
| TranslationBad...      | app/Controllers/Translation.php |
+------------------------+---------------------------------+

All operations done!

从源码看,无效键的判定逻辑在 findTranslationsInFile():语言键若不足两段(缺少文件名或键名)、或存在空段嵌套(键首尾带点号、连续点号等)会被归入 badLanguageKeys(system/Commands/Translation/LocalizationFinder.php)。

为更精确地搜索,可以指定要扫描的目录或 Locale:

php spark lang:find --dir Controllers/Translation --locale en --show-new

命令支持的全部选项(来自源码 $options 定义,system/Commands/Translation/LocalizationFinder.php):

选项 作用
--locale 指定写入语言文件的 Locale(如 en、ru),必须是 supportedLocales 之一
--dir 相对于 APPPATH 的扫描目录,不能指向 app/Language 本身
--show-new 只以表格展示新翻译,不写入文件
--verbose 输出详细信息(文件数、新翻译数、无效键表格)

如果指定的 --locale 不在 Config\App::$supportedLocales 中,命令会报错并返回 EXIT_USER_INPUT(system/Commands/Translation/LocalizationFinder.php)。

查看详细帮助:

php spark lang:find --help

十三、同步翻译文件到其他语言(lang:sync)

自 v4.6.0 起可用。命令实现位于 system/Commands/Translation/LocalizationSync.php,对应的测试见 tests/system/Commands/Translation/LocalizationSyncTest.php。

当完成当前语言的翻译后,你可能需要为另一种语言创建文件。可以使用 spark 的 lang:sync 命令辅助完成。不过它可能无法检测所有翻译,尤其是那些动态设置参数的情况,例如:

lang('App.status.' . $key, ['payload' => 'John'], 'en')

为了确保不遗漏翻译,最好的做法是复制已完成的语言文件并手动翻译——这样可以保留命令可能遗漏的独特键。

使用方法:

// Specify the locale for new/updated translations
php spark lang:sync --target ru

// or set the original locale
php spark lang:sync --locale en --target ru

命令选项(来自源码 $options 定义,system/Commands/Translation/LocalizationSync.php):

选项 作用
--locale 原始语言(默认取当前系统 Locale,如 en)
--target 目标语言(必填),必须与 --locale 不同

执行结果会得到带有翻译键的文件:源语言文件中已翻译的键值会被原样保留;目标语言中已有的重复键会被保留;缺失的键则以"文件名.键路径"占位值写入,等待人工翻译。

警告:新翻译中不匹配的键会被删除!因此在执行 lang:sync 前,请确认目标语言文件中没有需要保留的自定义键。

命令的校验逻辑相当严格(system/Commands/Translation/LocalizationSync.php):--locale 与 --target 都必须是 supportedLocales 中的合法值,二者不能相同,目标目录不存在时会自动创建(mkdir($targetLocaleDir, 0775))。合并逻辑 mergeLanguageKeys() 递归遍历源语言数组:目标中已存在的键保留旧值,缺失的字符串键写入 前缀.键 占位(嵌套键则递归处理),值类型只允许 array 或 string,否则抛出 LogicException(system/Commands/Translation/LocalizationSync.php)。

十四、完整工作流建议

综合以上机制,一个典型的多语言 CodeIgniter 4 项目落地路径如下:

  1. 在 app/Config/App.php 中设置 $defaultLocale、按需开启 $negotiateLocale,并维护 $supportedLocales 白名单;
  2. 在 app/Config/Routes.php 中按需使用 {locale} 路由占位符,配合 useSupportedLocalesOnly() 约束非法 Locale;
  3. 在 app/Language/{locale} 下编写语言文件,用 lang('File.key') 在视图与控制器中引用,利用嵌套键、参数替换与 ICU 格式化处理复数、货币、日期等场景;
  4. 安装 codeigniter4/translations 获取系统消息翻译,或在 app/Language 下覆盖个别键;
  5. 用 php spark lang:find 自动收集代码中的 lang() 键生成语言文件,再用 php spark lang:sync --target <locale> 为其他语言创建翻译骨架,最后人工翻译并格式化。

本地化能力在 CodeIgniter 4 中贯穿请求生命周期(IncomingRequest 的 Locale 检测)、字符串解析(Language 类的五级回退)与开发工具链(两个 spark 命令),理解这三层,就能把多语言支持稳定地落地到生产项目中。

登录后查看全文
CodeIgniter4