app.i18n - 国际化 API

多语言支持和本地化。

权限：L0 安全 — 无需声明，始终可用

方法

app.i18n.t(key, args?, default?)

获取翻译文本。

参数:

• key (string) - 翻译键
• args (array, 可选) - 插值参数数组，占位符从 {0} 起算
• default (string, 可选) - 默认值（键不存在时返回）

返回值: string - 翻译后的文本

-- 简单翻译
local text = app.i18n.t("menu.title")

-- 带参数（**占位符从 {0} 起算**，不是 {1}）
local text = app.i18n.t("file.count", {5})
-- 翻译文件中: "file.count": "共 {0} 个文件"
-- 结果: "共 5 个文件"

-- 多个参数依次 {0} {1} {2}
local text = app.i18n.t("result.size", {"1.2 MB", "800 KB"})
-- 翻译文件中: "result.size": "原始 {0}，压缩后 {1}"

-- 带默认值
local text = app.i18n.t("missing.key", nil, "默认文本")

app.i18n.locale()

获取当前语言环境。

返回值: string - 语言代码

local locale = app.i18n.locale()  -- "zh-Hans" 或 "en"

app.i18n.has(key)

检查翻译键是否存在。

参数:

• key (string) - 翻译键

返回值: boolean

if app.i18n.has("custom.message") then
    local text = app.i18n.t("custom.message")
end

app.i18n.locales()

获取插件支持的语言列表。

返回值: array - 语言代码数组

local locales = app.i18n.locales()
-- {"zh-Hans", "en"}

翻译文件格式

翻译文件位于插件目录的 locales/ 子目录，使用 JSON 格式：

locales/zh-Hans.json:

{
    "plugin.name": "图片工具",
    "menu.compress": "压缩图片",
    "message.processing": "正在处理 {0}/{1}...",
    "message.complete": "已处理 {0} 个文件"
}

locales/en.json:

{
    "plugin.name": "Image Tools",
    "menu.compress": "Compress Images",
    "message.processing": "Processing {0}/{1}...",
    "message.complete": "Processed {0} files"
}

示例

使用国际化的插件

function MyPlugin:handleCompress(context)
    local files = context.selectedFiles

    if #files == 0 then
        app.notification.show(
            app.i18n.t("plugin.name"),
            app.i18n.t("message.noFiles", nil, "请选择文件")
        )
        return
    end

    for i, file in ipairs(files) do
        app.log.info(app.i18n.t("message.processing", {i, #files}))
        -- 处理文件...
    end

    app.notification.show(
        app.i18n.t("plugin.name"),
        app.i18n.t("message.complete", {#files})
    )
end