ThinkPHP 多语言功能实战指南

前言

在开发多语言网站时，ThinkPHP 框架提供了完善的多语言支持机制。本文将详细介绍如何在 ThinkPHP 项目中实现多语言功能，包括配置文件设置、语言包编写以及语言切换等核心内容。

一、开启多语言配置

首先需要在配置文件中开启多语言功能。打开应用配置文件（通常为 config/app.php），添加或修改以下配置：

// 是否开启多语言
'lang_switch_on' => true,
// 默认语言
'default_lang' => 'zh-cn',

如果需要限制可用的语言列表，可以使用 Lang 类的静态方法：

use think\facade\Lang;

// 设置允许的语言列表
Lang::setAllowList(['zh-cn','en-us']);

二、编写语言包文件

ThinkPHP 支持多级语言包目录结构，按照优先级从高到低依次为：

• 框架语言包：thinkphp/lang/当前语言.php
• 应用语言包：application/lang/当前语言.php
• 模块语言包：application/模块/lang/当前语言.php

2.1 模块语言包示例

假设有一个 index 模块，语言包应放在 application/index/lang/ 目录下。

中文语言包（zh-cn.php）：

<?php
return [
    // 注册页面
    'reg_title' => '注册',
    'reg_small_title'=>'创建一个账户',
    'reg_email'=>'请输入你的邮箱',
    'reg_code'=>'请输入验证码',
    'reg_pwd'=>'请输入密码',
    'reg_submit'=>'创建账户',
    'reg_get_code'=>'获取验证码',
    'reg_opt_too_fast'=>'操作太频繁，请稍后再试',
    'reg_success'=>'注册成功',
    'reg_fail'=>'请求失败，请重试',
    'reg_email_exist'=>'邮箱已被使用',
    'reg_fail_email'=>'邮件发送失败',
    'reg_fail_code'=>'验证码错误',
    'reg_code_send'=>'发送成功，请留意您的邮箱',
    'reg_msg_code'=>'验证码是：',
    'reg_msg_wel'=>'欢迎注册会员，',
    'reg_code_time'=>'验证码半个小时后将失效',
    'reg_msg_title'=>'【站点】注册验证码'
];

英文语言包（en-us.php）：

<?php
return [
    // page register
    'reg_title' => 'Register',
    'reg_small_title'=>'Create your account',
    'reg_email'=>'Please input your email address',
    'reg_code'=>'Please input your verify code',
    'reg_pwd'=>'Please input your password',
    'reg_submit'=>'Create your account',
    'reg_get_code'=>'Get verify code',
    'reg_opt_too_fast'=>'Operation too fast, Please try again later',
    'reg_success'=>'Register success!',
    'reg_fail'=>'Request unsuccessful! Please try again',
    'reg_fail_email'=>'Email send fail',
    'reg_email_exist'=>'Email already exists',
    'reg_fail_code'=>'Verify code error',
    'reg_code_send'=>'We have sent you an email.',
    'reg_msg_code'=>'Verify code:',
    'reg_msg_wel'=>'Welcome to register,',
    'reg_code_time'=>'Verify code will expire after thirty minutes',
    'reg_msg_title'=>'[Site] Register verify code'
];

三、使用语言包

3.1 在模板中使用

在 ThinkPHP 模板引擎中，可以使用 lang 函数输出语言变量：

{:lang('reg_title')}

3.2 在控制器中使用

在控制器中可以通过以下方式获取语言变量：

// 使用 Lang 类
use think\facade\Lang;
Lang::get('reg_title');

// 或者使用助手函数
lang('reg_title');

四、语言切换

ThinkPHP 默认会自动检测用户浏览器语言进行自动切换。如果需要手动切换语言，有以下几种方式：

4.1 通过 URL 参数切换

在 URL 中添加 lang 参数即可切换语言：

https://example.com/index/index?lang=zh-cn
https://example.com/index/index?lang=en-us

4.2 通过 Cookie 切换

通过设置 think_var Cookie 来切换语言：

cookie('think_var', 'zh-cn');

五、最佳实践

• 语言包文件命名应遵循语言代码规范，如 zh-cn.php、en-us.php
• 建议按模块划分语言包，便于维护和管理
• 语言键名应使用有意义的命名，并添加注释说明用途
• 对于通用语言变量，可放在应用级语言包中
• 定期检查和更新语言包，确保多语言内容的一致性

总结

通过以上步骤，您可以在 ThinkPHP 项目中轻松实现多语言功能。合理组织语言包结构，遵循最佳实践，将有助于构建更加国际化的 Web 应用。