Plugin localization

Localization requires Plugin API 3.7.0, available in Eidos Lite 0.29.0 with Plugin SDK and tools 0.9.0 or later.

Declare a default language, message files, and complete README translations:

The localized-page starter includes this layout: eidos-plugin create my-localized-page --template localized-page. When generated by checkout tools, the project includes matching SDK/tools candidates in .eidos-toolchain/. Commit them with the project, then run npm install, npm run check -- --target lite, and npm run pack:plugin.

{
  "name": "%plugin.name%",
  "description": "%plugin.description%",
  "requires": { "pluginApi": "3.7.0" },
  "i18n": {
    "defaultLocale": "en",
    "messages": {
      "en": "./locales/en.json",
      "zh-CN": "./locales/zh-CN.json"
    },
    "readme": {
      "en": "./README.md",
      "zh-CN": "./README.zh-CN.md"
    }
  }
}

This is a fragment of plugin.json; retain the plugin’s ID, version and contributions. Message files contain a flat map of keys to plain strings:

{
  "plugin.name": "Recent History",
  "plugin.description": "Automatically records file openings",
  "search": "Search file paths…",
  "resultCount": "{count} matching files"
}

Use %key% as the complete value of a manifest display field. This works for plugin names/descriptions, contribution titles, settings labels/descriptions and connection titles. IDs, paths, permission declarations, defaults and stored values stay unchanged. Put every referenced key in the default language; other languages may omit keys and fall back individually.

Update the interface without clearing user state

The host supplies its resolved interface language. Views and action contexts expose ctx.i18n; no network or additional permission is needed.

const input = document.createElement("input")
root.append(input)
const updateLabels = () => {
  input.placeholder = ctx.i18n.t("search")
  input.setAttribute("aria-label", ctx.i18n.t("search"))
}
updateLabels()
ctx.subscriptions.add(ctx.i18n.onDidChangeLocale(updateLabels))

Change text in existing controls instead of rebuilding the page. Preserve the query, sorting, selection and draft when a language changes. Use ctx.i18n.t("resultCount", { count: 12 }) for named parameters and ctx.i18n.locale for locale-aware dates and numbers. Messages do not evaluate HTML, ICU or plural rules. Command and table-action runs retain their starting language. Background services do not restart or receive this presentation API.

Documentation and fallback

Matching tries the exact language tag, language plus script, base language, then the plugin default. Chinese Simplified and Traditional scripts are not interchanged. README selection uses one complete document; when only the default language is available, the host identifies it.

check validates the declarations and default messages. pack embeds the message files and README documents in a format 3 archive, so installed documentation works offline and matches the installed revision. Resources must be UTF-8 files inside the source directory, at most 1 MiB each. Relative README images are not bundled automatically; use explicit absolute image URLs if needed.

Generate a registry entry with eidos-plugin registry from that same archive. Its localized name and description are derived from the packaged dictionaries. Existing plugins without i18n continue to show their original strings.

Lite uses the resolved app language; the community site uses the page language. Both read the generated registry metadata for names and descriptions, then select one README from the verified release archive. A missing translation is identified instead of combining languages. Community permission summaries describe declared background capabilities, not a user’s live authorization or running state.