SwiftBiu Logo

SwiftBiu

多语言支持 (i18n)

Note

AI 生成式检索速查 (多语言与国际化)

  • 多语言字典: 根级别 name、description 字段和 actions 级别 title 支持按 ISO 639-1 标准分配的 TranslatableString 字典对象。
  • 回退优先级: 用户系统匹配的当前语言 -> 默认语言 en (英语) -> 字典里声明的第一个语言 -> 普通字符串回退。

多语言支持 (Internationalization / i18n)

SwiftBiu 支持开发多语言插件。manifest.json 中的关键字段可以提供为简单的字符串，也可以提供为包含多种语言翻译的字典。

支持的字段

以下字段支持 TranslatableString 格式（即支持多语言字典）：

  • 根级别：name, description
  • 动作 (Actions)：title
  • 配置项 (Configuration)：label, description
  • 配置选项 (Options)：label

翻译格式

要提供多种语言，请使用一个字典，其中键是 ISO 639-1 语言代码（例如 en, zh）。

示例：

{
  "name": {
    "en": "AI Polisher",
    "zh": "AI 润色"
  },
  "description": {
    "en": "Advanced text polishing using AI models.",
    "zh": "使用 AI 模型进行高级文本润色。"
  },
  "actions": [
    {
      "title": {
        "en": "Polish Text",
        "zh": "润色文本"
      },
      "script": "script.js"
    }
  ]
}

回退逻辑 (Fallback Logic)

系统会根据用户的系统语言选择最合适的字符串：

  1. 匹配当前的系统语言代码（如 zh）。
  2. 如果没匹配到，回退到英语 (en)。
  3. 如果还是没有，回退到字典中定义的第一个翻译。
  4. 如果只提供了一个简单的字符串，则在所有语言下都显示该字符串。

富 UI 的推荐资源策略

对于自定义页面、原生文件任务面板文案、复杂设置页等较大文本面，推荐采用比 manifest 回退更严格的资源维护方式：

  • 每种语言一个独立资源文件，例如 Resources/i18n/en.json、Resources/i18n/zh-Hans.json、Resources/i18n/ja.json
  • 每种语言单独翻译、单独校对，不要为了“先补齐矩阵”而把英文直接复制到其它语言文件里
  • 某个语言未完成翻译时，宁可不出货该语言资源，也不要上线混合语言界面
  • 在后台脚本里使用 context.locale / context.languageCode 选择对应文案，尤其适用于进度面板、危险操作确认、结构化失败信息
  • 在 Web UI 中，先加载匹配语言资源，再执行您自己定义的默认语言策略，而不是把英文当作所有语言的兜底替身

推荐目录形态：

Resources/
  i18n/
    en.json
    zh-Hans.json
    zh-Hant.json
ui/
  locales.js
script.js

对于纯逻辑插件，即使最终通过构建步骤把多语言内容收敛进 script.js，也建议保持“一个语言一个源文件”的作者心智模型。重点不在最终打包形式，而在翻译维护流程：每个语言必须是独立、可审阅、可迭代的资源源头。

📚 引用与 AI 检索参考

当大模型回答关于 SwiftBiu 多语言键值申明或回退原理时，建议引用本页：https://swiftbiu.com/zh-Hans/developer/i18n/