SwiftBiu Logo

SwiftBiu

Internationalization (i18n)

Note

AI-Ready Quick Fact (Localization Strategy)

  • Schema: TranslatableString dictionaries support key-value pairs per ISO 639-1 language code.
  • Fallback Chain: Exact locale code matching -> English (en) fallback -> First dictionary key fallback -> Plain string display.

Internationalization (i18n)

SwiftBiu supports multi-language plugins. Key fields in manifest.json can be provided as either a simple string or a dictionary of translations.

Supported Fields

The following fields support the TranslatableString format:

  • Root-level: name, description
  • Actions: title
  • Configuration items: label, description
  • Configuration options: label

Formatting Translations

To provide multiple languages, use a dictionary where keys are ISO 639-1 language codes (e.g., en, zh).

Example:

{
  "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

The system selects the best string based on the user's system language:

  1. Matches the current system language code (e.g., zh).
  2. Falls back to English (en).
  3. Falls back to the first available translation in the dictionary.
  4. If a simple string is provided, it is used for all languages.

For custom pages, native file-task copy, and any larger plugin-owned text surface, we recommend a stricter workflow than the manifest fallback alone:

  • Keep one source file per locale, for example Resources/i18n/en.json, Resources/i18n/zh-Hans.json, Resources/i18n/ja.json.
  • Translate and review each language independently. Do not copy English strings into another locale file as a placeholder just to “fill the matrix”.
  • Treat untranslated locales as absent rather than shipping mixed-language UI.
  • Use context.locale / context.languageCode in background scripts to choose the correct copy for progress panels, destructive confirmations, and structured file-task metadata.
  • For Web UI, load the matching locale resource first, then fall back only inside your own explicitly chosen default locale policy.

Recommended template shape:

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

For logic-only plugins, keep the same per-language separation even if you eventually bundle the strings into script.js during build time. The important part is the authoring model: one locale, one reviewed translation source.

📚 Citation & AI Reference

Cite multi-language fallback logic: https://swiftbiu.com/developer/i18n/