Translate
概览
Translate 让每位玩家选择一种语言，并用该语言阅读你服务器的内容。你在一个配置条目中声明各种语言，将文本写入 JSON 文件（其格式与 Triton 插件兼容，因此可以重用现有文件），并通过 <translate_key:your.key> 在任何接受 MiniMessage 占位符的地方显示它们。每位玩家都会看到自己语言的文本，当某个文本缺失时会回退到另一种语言。
在此基础上还有三项可选功能：已翻译的告示牌（告示牌以观看者所用的语言显示其文字）、构建为普通 GUI 页面的语言菜单和设置菜单，以及 AI 聊天翻译，即通过 AI 提供商或翻译引擎，为使用不同语言的观看者翻译聊天消息。
玩家的选择存储在构件中。语言按玩家保存，告示牌和聊天翻译的选择加入状态也是如此。
功能
- 语言列表 — 每种语言都有代码、横幅旗帜、显示名称、客户端区域设置、后备语言，以及被选中时要运行的动作。
- Triton 风格的 JSON 文件 — 文本和告示牌翻译，带有
%1、%2参数，从一个文件夹加载，无需重启即可重新加载。 - 后备链 — 先是请求的语言，然后是它的
fallbackLanguages，最后是主语言。 - 自动检测 — 可选择切换到与客户端区域设置匹配的语言。
- 已翻译的告示牌 — 在告示牌坐标处放置文本；玩家可以在设置菜单中选择退出。
- 由页面声明的菜单 — 使用 Translate 按钮类型，将语言菜单和设置菜单构建为 GUI 页面。
- AI 聊天翻译 — OpenRouter、OpenAI、DeepSeek、Groq、Mistral、Ollama、Anthropic、Gemini、LibreTranslate、DeepL 或任何与 OpenAI 兼容的服务器，并带有缓存。
- 语言事件与事实 — 在玩家更改语言时触发条目，并在条件中测试当前语言。
安装
- 安装 GUI 扩展以使用语言和设置菜单（如果你只使用命令，则为可选）。
- 可选地安装 MySQL 扩展：此时 AI 翻译缓存会保存在数据库中，否则只存在于内存中。
- 将 Translate 的 JAR 放入
plugins/Typewriter/extensions/并重启服务器。 - 创建文件夹
plugins/Typewriter/Translate/（它会在首次加载时自动创建），并将你的.json翻译文件放入其中。 - 如果你想通过占位符显示翻译，请安装 MiniPlaceholders。
快速上手
- 在 TypeWriter 网页面板中，打开一个**静态（static）**页面，添加一个 Player Language 构件：没有它，所选的语言不会被保存。
- 添加一个 Translation Config 条目。在
languages中添加en_GB和fr_FR：为每种语言设置name、flag（横幅代码）、displayName（例如&3Francais）、minecraftCodes（fr_FR、fr_CA），以及可选的fallbackLanguages。将mainLanguage设为en_GB。 - 创建
plugins/Typewriter/Translate/messages.json，内容如下，然后发布或运行/translate reload：
[
{
"type": "text",
"key": "welcome.message",
"languages": {
"en_GB": "&6Welcome to the server, %1!",
"fr_FR": "&6Bienvenue sur le serveur, %1 !"
}
}
]
- 在任何带有占位符的 MiniMessage 文本（对话、全息图、计分板）中使用
<translate_key:welcome.message>。运行/translate fr_FR的玩家现在会看到法语文本。 - 若要让玩家从菜单中选择，请使用 GUI 扩展构建一个菜单页面，在其上放置
translate_button:LANGUAGE#0、LANGUAGE#1…… 物品，在配置的languageMenu中引用它，并触发 Open Language Selector。
文本参数 %1、%2 只会由带参数调用翻译 API 的代码填充。<translate_key:...> 占位符只接受一个键，因此 %1 在那里会保持原样。
工作原理
玩家的语言按以下顺序解析：已保存的选择，然后是与客户端区域设置匹配的语言（minecraftCodes），最后是 mainLanguage。
翻译文件
文件是直接位于翻译文件夹（translationsFolder，默认为 plugins/Typewriter/ 内的 Translate）中的 .json 文件。每个文件是一个项目数组；文件也可以是一个对象，其 translations、items、languages、data 或 entries 下包含这样的数组。没有有效 type 和 key 的项目会被跳过，解析失败的文件会被记录并忽略。
文本项目有一个 key 和一个 languages 对象。& 颜色代码会被转换。键的查找较为宽容：先是完全匹配的键，然后是带有前缀 lang_、lang. 或 default. 的键，再是不区分大小写的匹配，最后是匹配最后一个 _ 或 . 之后的部分。
告示牌项目有 locations（world、x、y、z）以及按语言区分的 lines。最多读取 8 行，但只显示前 4 行（正面）。
{
"type": "sign",
"key": "shop.sign",
"locations": [{"world": "world", "x": 100, "y": 64, "z": 200}],
"lines": {
"en_GB": ["&b[Shop]", "&fClick to open", "", ""],
"fr_FR": ["&b[Boutique]", "&fCliquez pour ouvrir", "", ""]
}
}
当玩家在所列位置放置或编辑告示牌，或右键点击它时，告示牌会被翻译；玩家会通过客户端侧更新在告示牌上看到自己的语言。在设置菜单中关闭了告示牌翻译的玩家会看到原文。
菜单
语言菜单和设置菜单是 GUI 扩展的普通 open_gui 条目。Translate 提供了可放置在其物品上的按钮类型（GUI 物品的按钮类型字段）：
| 按钮类型 | 行为 |
|---|---|
translate_button:LANGUAGE#<n> | 配置中的第 n 种语言（从 0 开始）。显示代码，并在当前使用的语言上显示标记；左键点击选择它。超过最后一种语言后为空。 |
translate_button:TOGGLE_CHAT | 显示并切换玩家的 AI 聊天翻译（默认开启）。 |
translate_button:TOGGLE_SIGN | 显示并切换玩家的告示牌翻译（默认开启）。 |
在 Translation Config 中引用这些页面：选择器使用 languageMenu（以及用于特定视图的 languageMenuViewId），设置使用 settingsMenu（以及 settingsMenuViewId）。通过 Open Language Selector 或 Open Translation Settings 打开它们。/translate menu 会打开语言菜单。如果设置了 openSelectorCommandOverride，则控制台会改为运行该命令（{player} 会被替换为玩家名称）。
从菜单中选择语言需要 Player Language 构件：没有它，玩家会被告知该选择不会被保存。开关同样需要 Player AI Preference 和 Player Sign Preference 构件。
AI 聊天翻译
在 Translation Config 中配置 aiTranslation。设置 enabled，选择一个 provider，并提供 apiKey。除非设置了 apiBaseUrl 或 model，否则基础 URL 和模型默认取自该提供商；OPENAI_COMPATIBLE 需要 apiBaseUrl。建议将 env:VAR_NAME 用作 apiKey，以便从环境变量中读取密钥，而不是将其存储在页面中。
当玩家聊天时，消息会被翻译成每位语言与发送者不同且开启了聊天翻译的观看者的语言。翻译后的文本会替换观看者聊天中的消息，悬停其上会显示原文。聊天最多等待 chatTranslationTimeoutMs（默认 800 毫秒）来获取翻译，然后向仍在等待的观看者显示未翻译的消息。匹配 noTranslateRegex（默认为命令和纯数字）的消息不会被发送，匹配 censorRegex 的文本在发送前会被替换为 ***，并且 enabledSections 必须包含 CHAT。
连续三次请求失败后，AI 翻译会自动禁用，直到下一次重新加载翻译。结果按消息和语言缓存，如果存在 MySQL 扩展则缓存在数据库中，否则缓存在内存中。
命令
命令是 /translate，别名为 /lang 和 /language。只能由玩家运行。
| 命令 | 说明 |
|---|---|
/translate | 显示帮助。 |
/translate <language> | 通过其配置的名称设置你的语言（例如 fr_FR）。 |
/translate list | 列出已配置的语言，并标记你的语言。 |
/translate menu | 打开语言选择器。 |
/translate toggle_ai | 为你切换 AI 聊天翻译。 |
/translate sign set <key> | 将你注视的告示牌（5 格以内）标记为用此键翻译。需要 typewriter.translate.admin。 |
/translate sign remove | 移除该告示牌的标记。需要 typewriter.translate.admin。 |
/translate sign info | 显示该告示牌的键、位置和翻译。需要 typewriter.translate.admin。 |
/translate reload | 重新加载翻译文件。需要 typewriter.translate.admin。 |
/translate sign set 只会在告示牌上写入一个标记和键。实际的文本来自 JSON 文件中带有该告示牌位置的 sign 项目。
权限
| 权限 | 授予 |
|---|---|
typewriter.translate.admin | /translate reload 和 /translate sign ...。 |
占位符
MiniPlaceholders 扩展 translate，可作为 MiniMessage 标签使用。翻译后的文本可以包含 MiniMessage 标记和嵌套的占位符。
| 占位符 | 返回 |
|---|---|
<translate_key:some.key> | 该键在观看者语言中的文本。如果缺失，则为红色的 [Translation not found: key]。 |
<translate_lang> | 观看者的语言代码，例如 fr_FR。 |
<translate_lang_display> | 语言的显示名称。 |
<translate_lang_flag> | 语言的横幅旗帜代码。 |
<translate_count> | 已加载的翻译数量（文本加告示牌）。 |
<translate_languages> | 已配置的语言数量。 |
条目
10 个条目，由扩展源码生成。
动作4
- Open Language Selector ActionOpen the language selection menu
- Open Translation Settings ActionOpen the translation settings menu
- Reload Translations ActionReload translation files from disk
- Set Language ActionSet a player's translation language
事件1
- Player Language Change EventTriggered when a player changes their language
事实1
- Player Language FactReturns the player's current language as a numeric value
构件3
- Player Ai Preference ArtifactStores player AI translation preferences
- Player Language ArtifactStores player language preferences
- Player Sign Preference ArtifactStores player sign translation preferences
清单1
- Translation ConfigConfigure the multi-language translation system
故障排查
出现 [Translation not found: key]。 该键不在任何已加载的文件中，或者文件加载失败。请检查服务器日志中是否有 Failed to load translation file，验证 JSON，并运行 /translate reload。请确保文件直接位于 plugins/Typewriter/Translate/ 中（不会读取子文件夹），并且扩展名为 .json。
每次登录时语言都会重置。 没有发布 Player Language 构件，因此选择没有被存储。请添加一个。
菜单没有任何作用。 日志显示 No 'languageMenu' configured 或 No 'settingsMenu' configured：请在 Translation Config 中设置菜单页面。对于语言菜单，当 openSelectorCommandOverride 不为空时，它具有优先权。
语言没有跟随客户端语言。 在没有已保存选择的情况下，如果客户端区域设置出现在某种语言的 minecraftCodes 中，则会自动使用它。每当客户端报告了与另一种语言匹配的区域设置变化时，forceClientLocaleOnJoin 还会额外切换玩家的语言，并覆盖其已保存的选择。
AI 翻译停止工作。 请在日志中查找 AUTOMATICALLY DISABLED：连续三次 API 失败会将其关闭。请修复密钥、URL 或模型，然后运行 /translate reload。apiKey references env var ... not set 表示缺少该环境变量。
告示牌没有被翻译。 告示牌必须恰好位于 JSON 文件中某个 sign 项目所列出的坐标，并且世界名称正确。玩家不能关闭告示牌翻译，并且告示牌是在被放置或被右键点击时翻译的。
相关扩展
- TinyEssentials — 当 AI 翻译包装聊天渲染器时，会保留其聊天格式。
- MySQL — 持久化的 AI 翻译缓存。