> For the complete documentation index, see [llms.txt](https://ak-scripts.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ak-scripts.gitbook.io/docs/yi-lai/markdown/gong-neng-mo-kuai-dao-chu/ben-di-hua-locales.md).

# 本地化（Locales）

## 🌐 Locales（本地化）模块导出文档

### 📋 概述

Locales 模块是 ak-lib 的多语言本地化系统，支持自动扫描依赖 ak-lib 的资源语言文件，提供统一的翻译接口。支持嵌套 key、热加载等功能。

### 🚀 导出方式

#### 服务端

**方式 1：直接翻译函数（推荐）⭐**

```lua
local text = exports['ak-lib']:Translate('menu.open.title')
```

**方式 2：指定资源翻译**

```lua
local text = exports['ak-lib']:Translate('my-plugin', 'menu.open.title')
```

**方式 3：手动加载语言文件**

```lua
exports['ak-lib']:LoadLocales('my-plugin')
```

#### 客户端

**方式 1：获取模块对象（推荐）⭐**

```lua
local Locales = exports['ak-lib']:Locales()
local text = Locales.t('menu.open.title')
```

**方式 2：直接翻译函数**

```lua
local text = exports['ak-lib']:t('menu.open.title')
```

**方式 3：指定资源翻译**

```lua
local text = exports['ak-lib']:tFor('my-plugin', 'menu.open.title')
```

### 📖 可用导出

#### 服务端

| 导出                                     | 说明         | 参数                                                             | 返回值     |
| -------------------------------------- | ---------- | -------------------------------------------------------------- | ------- |
| `Translate(key, locale)`               | 翻译关键字      | `key` (string), `locale` (string, 可选)                          | string  |
| `Translate(resourceName, key, locale)` | 翻译指定资源的关键字 | `resourceName` (string), `key` (string), `locale` (string, 可选) | string  |
| `LoadLocales(resourceName)`            | 手动加载语言文件   | `resourceName` (string)                                        | boolean |

#### 客户端

| 导出                                | 说明         | 参数                                                             | 返回值            |
| --------------------------------- | ---------- | -------------------------------------------------------------- | -------------- |
| `Locales()`                       | 返回模块对象     | -                                                              | `AKLocales` 对象 |
| `t(key, locale)`                  | 翻译关键字      | `key` (string), `locale` (string, 可选)                          | string         |
| `tFor(resourceName, key, locale)` | 翻译指定资源的关键字 | `resourceName` (string), `key` (string), `locale` (string, 可选) | string         |

**模块对象方法**

使用 `exports['ak-lib']:Locales()` 获取的对象包含以下方法：

| 方法                                | 说明         | 参数                                   | 返回值    |
| --------------------------------- | ---------- | ------------------------------------ | ------ |
| `t(key, locale)`                  | 翻译关键字      | `key`, `locale` (可选)                 | string |
| `tFor(resourceName, key, locale)` | 翻译指定资源的关键字 | `resourceName`, `key`, `locale` (可选) | string |

### 💡 使用示例

#### 服务端：基础翻译

```lua
-- 方式 1：自动识别资源（推荐）
local text = exports['ak-lib']:Translate('menu.open.title')
print(text)  -- 输出翻译后的文本

-- 方式 2：指定资源
local text = exports['ak-lib']:Translate('my-plugin', 'menu.open.title')
print(text)

-- 方式 3：指定语言
local text = exports['ak-lib']:Translate('menu.open.title', 'en')
print(text)
```

#### 客户端：基础翻译

```lua
-- 方式 1：使用模块对象（推荐）
local Locales = exports['ak-lib']:Locales()
local text = Locales.t('menu.open.title')
print(text)

-- 方式 2：直接调用
local text = exports['ak-lib']:t('menu.open.title')
print(text)

-- 方式 3：指定资源
local text = exports['ak-lib']:tFor('my-plugin', 'menu.open.title')
print(text)
```

#### 嵌套 key 支持

语言文件支持嵌套结构：

```json
// locales/zh-CN.json
{
  "menu": {
    "open": {
      "title": "打开菜单"
    },
    "close": "关闭"
  },
  "welcome": "欢迎使用"
}
```

使用嵌套 key：

```lua
-- 服务端
local title = exports['ak-lib']:Translate('menu.open.title')  -- "打开菜单"
local close = exports['ak-lib']:Translate('menu.close')       -- "关闭"
local welcome = exports['ak-lib']:Translate('welcome')        -- "欢迎使用"

-- 客户端
local Locales = exports['ak-lib']:Locales()
local title = Locales.t('menu.open.title')
local close = Locales.t('menu.close')
local welcome = Locales.t('welcome')
```

#### 字符串格式化

支持字符串格式化（使用 `string.format`）：

```json
// locales/zh-CN.json
{
  "greeting": "你好，%s！",
  "item_count": "你有 %d 个 %s"
}
```

```lua
-- 服务端
local greeting = exports['ak-lib']:Translate('greeting', '玩家名')  -- "你好，玩家名！"
local count = exports['ak-lib']:Translate('item_count', 5, '面包')  -- "你有 5 个 面包"

-- 注意：Translate 函数会自动处理格式化参数
-- 实际上是通过 pcall 调用，内部使用 string.format
```

#### 手动加载语言文件

```lua
-- 服务端：手动加载指定资源的语言文件
local success = exports['ak-lib']:LoadLocales('my-plugin')
if success then
    print("语言文件加载成功")
else
    print("语言文件加载失败")
end
```

#### 完整示例：商店插件

**语言文件**

```json
// locales/zh-CN.json
{
  "shop": {
    "title": "商店",
    "buy_success": "成功购买 %d 个 %s",
    "buy_fail": "购买失败：%s",
    "not_enough_money": "金钱不足",
    "inventory_full": "背包已满"
  }
}
```

```json
// locales/en.json
{
  "shop": {
    "title": "Shop",
    "buy_success": "Successfully purchased %d %s",
    "buy_fail": "Purchase failed: %s",
    "not_enough_money": "Not enough money",
    "inventory_full": "Inventory full"
  }
}
```

**服务端代码**

```lua
RegisterServerEvent('shop:buyItem', function(itemName, count)
    local source = source
    
    -- 使用翻译
    local notEnoughMoney = exports['ak-lib']:Translate('shop.not_enough_money')
    local inventoryFull = exports['ak-lib']:Translate('shop.inventory_full')
    local buySuccess = exports['ak-lib']:Translate('shop.buy_success', count, itemName)
    local buyFail = exports['ak-lib']:Translate('shop.buy_fail', '未知错误')
    
    -- 购买逻辑...
    if not hasMoney then
        TriggerClientEvent('ak-lib:Notify', source, {
            type = 'error',
            message = notEnoughMoney
        })
        return
    end
    
    -- ...
end)
```

**客户端代码**

```lua
local Locales = exports['ak-lib']:Locales()

-- 打开商店 UI
function OpenShop()
    local title = Locales.t('shop.title')
    -- 显示商店 UI，使用 title
end

-- 购买成功提示
function OnBuySuccess(count, itemName)
    local message = Locales.t('shop.buy_success', count, itemName)
    exports['ak-lib']:Notify({
        type = 'success',
        message = message
    })
end
```

### 📝 API 详细说明

#### 自动扫描机制

Locales 模块会自动扫描所有在 `fxmanifest.lua` 中声明 `dependency { 'ak-lib' }` 的资源，并加载它们的语言文件。

**语言文件位置：**

```
your-plugin/
  locales/
    zh-CN.json
    en.json
```

#### GetInvokingResource() 机制

在 export/event/callback 场景下，`Translate()` 函数会自动识别调用资源：

```lua
-- 在 my-plugin 资源中调用
local text = exports['ak-lib']:Translate('menu.open.title')
-- 自动使用 my-plugin 资源的语言文件
```

**注意：** 在定时器、CreateThread 等场景下可能返回 `nil`，此时会 fallback 到 'ak-lib'。

#### Fallback 顺序

如果找不到指定语言的翻译，会按以下顺序回退：

1. 当前语言（`Config.Locale`）
2. 'zh-CN'（中文，如果是中文相关）
3. 'zh'（中文通用）
4. 'en'（英文）

#### 语言代码格式

支持标准的 locale 格式：

* `zh-CN`（简体中文）
* `en`（English）
* `en-US`（美式英语）
* `zh-TW`（繁体中文）

语言代码会自动规范化（下划线转换为连字符，大小写统一）。

#### 字符串格式化

翻译函数支持 `string.format` 风格的格式化：

```lua
-- 语言文件
{
  "message": "你好，%s！你有 %d 个物品"
}

-- 使用
local text = exports['ak-lib']:Translate('message', '玩家名', 10)
-- 输出: "你好，玩家名！你有 10 个物品"
```

**注意：** 格式化是通过 `string.format` 实现的，需要确保参数数量和类型匹配。

### ⚠️ 注意事项

1. **GetInvokingResource() 限制**：在定时器、CreateThread 等场景下可能返回 `nil`，此时会使用 'ak-lib' 的语言文件。
2. **嵌套 key**：支持使用点号分隔的嵌套 key，如 `"menu.open.title"`。
3. **类型检查**：如果中间层不是 table，嵌套访问会返回 key 本身。
4. **文件扫描**：优先使用 `LoadResourceFile` API，避免使用 `io.popen`（部分环境可能被禁用）。
5. **热加载支持**：资源热加载时会自动更新语言文件。
6. **服务端统一语言**：客户端的语言由服务端的 `Config.Locale` 决定，会自动同步。
7. **语言文件格式**：必须是有效的 JSON 格式。
8. **资源依赖**：只有声明了 `dependency { 'ak-lib' }` 的资源的语言文件才会被自动扫描。
9. **格式化参数**：使用字符串格式化时，确保参数数量和类型匹配，否则可能出错。
10. **推荐使用模块对象**：客户端推荐使用 `Locales()` 获取模块对象，代码更清晰。

### 🔗 相关文档

* 本地化说明


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://ak-scripts.gitbook.io/docs/yi-lai/markdown/gong-neng-mo-kuai-dao-chu/ben-di-hua-locales.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.