# 本地化文本（LocalString）

MT 管理器自带了多种语言包，可在不同语言环境下显示不同的语言。为了在插件中支持多国语言，插件 API 提供了完整的本地化文本支持。

# 语言包文件

# 命名格式

语言包需要放在插件安装包的 assets 文件夹中，命名格式为：

文件名	说明
`语言包名称.mtl`	基础语言包（通常使用英文）
`语言包名称-区域代码.mtl`	指定区域的语言包

默认语言包：插件的默认语言包名称为 strings，使用 getString("key") 时会从此语言包获取文本。

示例（默认语言包 strings）：

strings.mtl - 基础语言包
strings-zh-CN.mtl - 简体中文
strings-zh-TW.mtl - 繁体中文
strings-ru.mtl - 俄语

自定义语言包：也可以创建其他名称的语言包，通过 getString("pack:key") 格式访问。

示例（自定义语言包 errors）：

errors.mtl - 基础语言包
errors-zh-CN.mtl - 简体中文

// 从默认语言包 strings 获取
context.getString("plugin_name");

// 从自定义语言包 errors 获取
context.getString("errors:network_error");
context.getString("errors:file_not_found");

// 在 UI 组件中使用
builder.addTextView().text("{errors:network_error}");

# 内容格式

语言包采用简单的键值对格式：

# 这是注释
plugin_name: 我的插件
plugin_description: 这是插件描述

# 支持转义字符：\n \r \t \\
multiline: 第一行\n第二行\n第三行

# 续行符（行尾的反斜杠）
long_text: 这是一段很长的文本，\
可以使用续行符分成多行书写，\
最终会合并为一行。

格式说明：

键值对格式：key: 内容（冒号后需加空格）
注释：以 # 开头的行
转义字符：\n（换行）、\r（回车）、\t（制表符）、\\（反斜杠）
续行符：行尾的 \ 表示下一行继续

# 语言包优先级

系统会按以下顺序查找本地化文本：

当前语言的完整区域代码（如 strings-zh-CN.mtl）
当前语言的语言代码（如 strings-zh.mtl）
基础语言包（如 strings.mtl）

回退机制：仅 strings 语言包支持回退到 MT 内置语言包。当使用 getString("key") 或 getString("{key}") 时，如果在插件的 strings 语言包中找不到对应词条，会自动回退到 MT 内置的 strings 语言包查找。这使得插件可以直接使用 MT 内置的通用词条（如 ok、cancel、error 等）。

使用 getString("pack:key") 访问其他语言包时没有回退机制，找不到词条会抛出异常。

# MT 内置词条

以下词条可直接在插件中使用，无需在自己的语言包中定义：

# 对话框按钮
ok: 确定
cancel: 取消
close: 关闭

# 对话框标题
## 三个中文翻译都是提示，但其它语言翻译不一样，使用场景也不同
## tip：小贴士，notice：一般通知，information：信息提示
tip: 提示
notice: 提示
information: 提示
warning: 警告
error: 错误

# 任务进度标题
loading: 正在加载…
preparing: 正在准备…
reloading: 正在重新加载…
processing: 正在处理…
canceling: 正在取消…

# 其它
press_again_to_cancel: 再按一次取消操作
out_of_memory_error: 运行内存不足
dual_progress_dialog_total: 总进度

使用示例：

// 直接使用内置词条
builder.addButton().text("{ok}");
builder.addButton().text("{cancel}");

// 对话框标题
pluginUI.showMessage("{warning}", "警告内容");
pluginUI.showMessage("{error}", "错误信息");

# getString() 方法详解

# 支持的 key 格式

格式	说明	示例
`key`	从 strings 语言包获取，未找到则回退到 MT 内置语言包	`getString("ok")`
`pack:key`	从指定语言包获取，无回退	`getString("example:key")`
`{key}`	等价于 `key`	`getString("{ok}")`
`{pack:key}`	等价于 `pack:key`	`getString("{example:key}")`

# 方法列表

// 获取本地化文本
String getString(String key);

// 获取并格式化
String getString(String key, Object... formatArgs);

// 获取本地化文本，未找到返回 null
String getStringNullable(String key);

// 批量获取
List<String> getStringList(String... keys);
String[] getStringArray(String... keys);

# 使用示例

// 基本用法
String name = context.getString("plugin_name");

// 带格式化参数
// 假设 hello_format = "你好，%s！欢迎使用 %s"
String msg = context.getString("hello_format", userName, appName);

// 批量获取（用于 Spinner 等组件）
List<String> items = context.getStringList(
    "{option_1}",
    "{option_2}",
    "{option_3}"
);

# 在 UI 组件中使用

UI 组件直接支持 {key} 格式的本地化文本：

// 文本视图
builder.addTextView().text("{plugin_name}");

// 按钮
builder.addButton().text("{ok}");

// 编辑框提示
builder.addEditText().hint("{input_hint}");

// 对话框
pluginUI.buildDialog()
    .setTitle("{dialog_title}")
    .setMessage("{dialog_message}")
    .setPositiveButton("{ok}", null)
    .setNegativeButton("{cancel}", null)
    .show();

// Toast 消息
context.showToast("{operation_success}");
context.showToast("{hello_format}", userName);

注意：只有 String 类型的文本才会进行本地化转换。如果需要显示原始的 {key} 文本，可使用 CharSequence 类型，如 new SpannedString("{key}")。

# 在清单文件中使用

在 manifest.json 中可以使用 {key} 格式设置插件名称和描述：

{
    "name": "{plugin_name}",
    "description": "{plugin_description}",
    ...
}

# 全球语言名称

MT 内置了全球常见语言的名称语言包（lang），主要用于翻译引擎显示语言选项：

// 获取语言名称
context.getString("lang:auto");   // 自动检测
context.getString("lang:en");     // 英语
context.getString("lang:zh-CN");  // 简体中文
context.getString("lang:ja");     // 日语

完整语言代码表

auto: 自动检测
af: 南非荷兰语
am: 阿姆哈拉语
ar: 阿拉伯语
az: 阿塞拜疆语
be: 白俄罗斯语
bg: 保加利亚语
bn: 孟加拉语
bs: 波斯尼亚语
ca: 加泰罗尼亚语
ceb: 宿务语
co: 科西嘉语
cs: 捷克语
cy: 威尔士语
da: 丹麦语
de: 德语
el: 希腊语
en: 英语
eo: 世界语
es: 西班牙语
et: 爱沙尼亚语
eu: 巴斯克语
fa: 波斯语
fi: 芬兰语
fr: 法语
fy: 弗里西语
ga: 爱尔兰语
gd: 苏格兰盖尔语
gl: 加利西亚语
gu: 古吉拉特语
ha: 豪萨语
haw: 夏威夷语
hi: 印地语
hmn: 苗语
hr: 克罗地亚语
ht: 海地克里奥尔语
hu: 匈牙利语
hy: 亚美尼亚语
id: 印尼语
ig: 伊博语
is: 冰岛语
it: 意大利语
iw: 希伯来语
ja: 日语
jw: 印尼爪哇语
ka: 格鲁吉亚语
kk: 哈萨克语
km: 高棉语
kn: 卡纳达语
ko: 韩语
ku: 库尔德语
ky: 吉尔吉斯语
la: 拉丁语
lb: 卢森堡语
lo: 老挝语
lt: 立陶宛语
lv: 拉脱维亚语
mg: 马尔加什语
mi: 毛利语
mk: 马其顿语
ml: 马拉雅拉姆语
mn: 蒙古语
mr: 马拉地语
ms: 马来语
mt: 马耳他语
my: 缅甸语
ne: 尼泊尔语
nl: 荷兰语
no: 挪威语
ny: 齐切瓦语
pa: 旁遮普语
pl: 波兰语
ps: 普什图语
pt: 葡萄牙语
ro: 罗马尼亚语
ru: 俄语
sd: 信德语
si: 僧伽罗语
sk: 斯洛伐克语
sl: 斯洛文尼亚语
sm: 萨摩亚语
sn: 修纳语
so: 索马里语
sq: 阿尔巴尼亚语
sr: 塞尔维亚语
st: 塞索托语
su: 印尼巽他语
sv: 瑞典语
sw: 斯瓦希里语
ta: 泰米尔语
te: 泰卢固语
tg: 塔吉克语
th: 泰语
tl: 菲律宾语
tr: 土耳其语
tt: 塔塔尔语
ug: 维吾尔语
uk: 乌克兰语
ur: 乌尔都语
uz: 乌兹别克语
vi: 越南语
xh: 南非科萨语
yi: 意第绪语
yo: 约鲁巴语
zh: 中文
zh-CN: 简体中文
zh-TW: 繁体中文
zu: 南非祖鲁语

← API - 插件上下文 API - 插件UI →