CodeIgniter 4 本地化(Localization)完全指南:从 Locale 配置到语言文件自动化生成
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 检测方式:
- 内容协商(Content Negotiation):一种"设置后即忘"(set and forget)的方法,自动执行内容协商来决定正确的 Locale。
- 路由内检测(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 项目落地路径如下:
- 在 app/Config/App.php 中设置
$defaultLocale、按需开启$negotiateLocale,并维护$supportedLocales白名单; - 在 app/Config/Routes.php 中按需使用
{locale}路由占位符,配合useSupportedLocalesOnly()约束非法 Locale; - 在 app/Language/{locale} 下编写语言文件,用
lang('File.key')在视图与控制器中引用,利用嵌套键、参数替换与 ICU 格式化处理复数、货币、日期等场景; - 安装
codeigniter4/translations获取系统消息翻译,或在 app/Language 下覆盖个别键; - 用
php spark lang:find自动收集代码中的lang()键生成语言文件,再用php spark lang:sync --target <locale>为其他语言创建翻译骨架,最后人工翻译并格式化。
本地化能力在 CodeIgniter 4 中贯穿请求生命周期(IncomingRequest 的 Locale 检测)、字符串解析(Language 类的五级回退)与开发工具链(两个 spark 命令),理解这三层,就能把多语言支持稳定地落地到生产项目中。