ThinkPHP 多語言包完整實作：從配置到視圖的逐步指南

前言

ThinkPHP 內建強大的多語言支援機制，透過語言包檔案與行為擴展實現零侵入式國際化。本文以 ThinkPHP 3.2 為例，完整記錄從配置開啟、語言偵測、語言包建立、視圖輸出到後台控制器使用的全流程，並補充常見坑點與最佳實踐。

步驟 1：開啟多語言功能

編輯專案配置 `Home/Conf/config.php`：

<?php
return array(
    // 開啟語言包功能
    'LANG_SWITCH_ON'   => true,
    // 自動偵測瀏覽器語言
    'LANG_AUTO_DETECT' => true,
    // 預設語言
    'DEFAULT_LANG'     => 'zh-cn',
    // 允許切換的語言列表（逗號分隔）
    'LANG_LIST'        => 'en-us,zh-cn,zh-tw',
    // URL 切換語言的變數名
    'VAR_LANGUAGE'     => 'l',
);
?>

步驟 2：註冊語言檢測行為

建立 `Home/Conf/tags.php`，掛載 `app_begin` 標籤：

<?php
return array(
    'app_begin' => array('CheckLang')
);
?>

步驟 3：確保行為類別存在

框架完整版包含 `ThinkPHP/Extend/Behavior/CheckLangBehavior.class.php`。若專案為精簡版，請手動複製至 `Home/Lib/Behavior/CheckLangBehavior.class.php`。核心邏輯如下：

• 讀取配置判斷是否啟用多語言。
• 優先級：URL 參數 (`l=en-us`) > Cookie (`think_language`) > 瀏覽器 `HTTP_ACCEPT_LANGUAGE` > 預設語言。
• 驗證語言是否在 `LANG_LIST` 白名單，非法則回退預設。
• 定義常數 `LANG_SET` 為當前語言代碼（小寫）。
• 依序載入：框架公共語言包 → 專案公共語言包 → 分組語言包 → 模組語言包。

步驟 4：建立語言包檔案

在 `Home/Lang/` 下建立三個語言目錄，各放一個 `common.php`：

Home/Lang/
├── zh-cn/common.php   // 簡體中文
├── zh-tw/common.php   // 繁體中文
├── en-us/common.php   // 英文

zh-cn/common.php

<?php
return array(
    'welcome' => '歡迎使用 ThinkPHP',
    'login'   => '登入',
    'logout'  => '登出',
);
?>

zh-tw/common.php

<?php
return array(
    'welcome' => '歡迎使用 ThinkPHP',
    'login'   => '登入',
    'logout'  => '登出',
);
?>

en-us/common.php

<?php
return array(
    'welcome' => 'Welcome to ThinkPHP',
    'login'   => 'Login',
    'logout'  => 'Logout',
);
?>

步驟 5：視圖模板中使用語言變數

建立 `Home/Tpl/Index/index.html`：

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>ThinkPHP 多語言示例</title>
</head>
<body>
    <div class="main">
        <div>
            切換語言：
            <a href="?l=zh-cn">簡體中文</a> |
            <a href="?l=zh-tw">繁體中文</a> |
            <a href="?l=en-us">English</a>
        </div>
        <div class="result">{$Think.lang.welcome}</div>
        <p>{$Think.lang.login} | {$Think.lang.logout}</p>
    </div>
</body>
</html>

步驟 6：控制器與模型中呼叫

使用 `L()` 函式（`Think\Think::L()` 的快捷方式）：

<?php
namespace Home\Controller;
use Think\Controller;

class UserController extends Controller {
    public function login() {
        // 直接輸出對應語言文字
        $this->error(L('login_failed')); // 需在語言包定義 login_failed
    }
    
    public function profile() {
        // 取得字串供模板使用
        $title = L('user_profile');
        $this->assign('pageTitle', $title);
        $this->display();
    }
}
?>

進階：模組專屬語言包

若 `User` 模組有專屬術語，可在 `Home/Lang/zh-cn/User.php` 定義：

<?php
return array(
    'user_profile' => '個人資料',
    'login_failed' => '帳號或密碼錯誤',
);
?>

框架會自動載入 `Lang/zh-cn/User.php`（普通分組模式）或 `Lang/zh-cn/User/User.php`（獨立分組模式）。

常見問題與解決方案

最佳實踐建議

1. 統一鍵名規範：採用 `module.action.desc` 格式（如 `user.login.success`），避免衝突。
2. 語言包模組化：大型專案按模組拆分語言檔，載入時按需合併，減少記憶體佔用。
3. 後台管理介面：建立語言包管理 CRUD，支援匯入/匯出 CSV/Excel，方便翻譯人員協作。
4. 預設值機制：`L('key', '預設文字')` 可在鍵缺失時回退，避免畫面顯示鍵名。
5. ThinkPHP 5/6/8 遷移：新版本改用 `lang/` 目錄、PHP 陣列回傳、中間件替代行為，核心概念不變，遷移參考官方文件。

目錄結構總覽

Home/
├── Conf/
│   ├── config.php      # 開啟多語言配置
│   └── tags.php        # 掛載 CheckLang 行為
├── Lang/
│   ├── zh-cn/
│   │   ├── common.php
│   │   └── User.php
│   ├── zh-tw/
│   │   └── common.php
│   └── en-us/
│       └── common.php
├── Lib/Behavior/
│   └── CheckLangBehavior.class.php (若精簡版需自行複製)
└── Tpl/Index/index.html # 視圖使用 {$Think.lang.key}