Skip to main content
Version: 0.4.x(Latest)

Overview​

Source plugins obtain runtime translation capabilities through services.I18n(). This capability reads the translation catalog already loaded by the host and returns localized text based on the current request language.

Dynamic plugin note: the hostServices catalog does not include an i18n service. Dynamic plugins can deliver manifest/i18n resources with the plugin package, but the discovery, merging, caching, invalidation, and frontend runtime distribution of those resources are all managed by the host. Dynamic plugin backends should not directly read, merge, or translate their own language packs, nor should they declare service: i18n in plugin.yaml.

Capability phase: Runtime

Type support: Source plugins

Capability Design​

Translation Catalog vs. Plugin Resources​

I18nService consumes the host's runtime translation catalog; plugin manifest/i18n is a static delivery resource. They have different responsibilities:

ContentRole
I18nServiceSource plugins query translation text that has been loaded and participates in runtime resolution
manifest/i18nSource plugins and dynamic plugins deliver language resources, unified discovery and merging by the host resource pipeline

Dynamic plugins do not need to read language packs via manifest.get for runtime translation. Reading a language pack file is not the same as registering translations; how translation resources are loaded during installation, upgrade, or runtime is handled by the host plugin resource pipeline.

Translation Fallback Mechanism​

The fallback text in Translate is important. When the translation catalog misses, the host returns the fallback text to ensure notifications, logs, and page prompts remain readable. Plugin business copy, notification titles, and audit text should use stable keys and provide readable fallback text.

Search Capability Scope​

FindMessageKeys is suited for admin scenarios such as log filtering and API documentation filtering, and should not be used in high-frequency request paths.

Interface Definitions​

Source Plugin Interface​

MethodDescription
GetLocaleReturns the effective language for the current request
TranslateReturns localized text based on the translation key and fallback text
FindMessageKeysSearches translation keys by localized text keyword within a specified prefix

Dynamic Plugin Interface​

The dynamic hostServices catalog does not publish a standalone i18n service. The internationalization boundary for dynamic plugins is as follows:

NeedApproach
Deliver plugin language resourcesPlace resources in manifest/i18n/<locale>/, loaded by the host resource pipeline
Return localizable business resultsReturn a stable messageKey, messageParams, and English fallback, or return raw business data
Runtime translation and language switchingHandled by host error governance, frontend runtime language packs, or the host unified display layer

Usage​

Source Plugin Usage​

Source plugins perform runtime translation through services.I18n():

// Get the current request language
locale := services.I18n().GetLocale(ctx)

// Return localized text by translation key
text := services.I18n().Translate(ctx, "plugin.reports.export.success", "Export succeeded")

// Search translation keys
keys := services.I18n().FindMessageKeys(ctx, "plugin.reports", "export")

Dynamic Plugin Usage​

Dynamic plugins should not declare a nonexistent service: i18n in plugin.yaml, nor should they read manifest/i18n and translate on their own. The backend can return stable message keys, parameters, and fallback text:

type ExportResult struct {
    MessageKey    string         `json:"messageKey"`
    MessageParams map[string]any `json:"messageParams"`
    Fallback      string         `json:"fallback"`
}

return &ExportResult{
    MessageKey:    "plugin.reports.export.success",
    MessageParams: map[string]any{"count": 12},
    Fallback:      "Export completed",
}, nil

Final display text is handled by host error governance, frontend runtime language packs, or the host unified display layer.

Design Constraints​

  • Source plugins use services.I18n(). This is the currently published runtime translation entry point.
  • Dynamic plugins do not declare an i18n service. The latest pluginbridge/protocol.HostServiceDescriptors() does not publish this service.
  • Dynamic plugins do not handle language packs on their own. manifest/i18n resources are loaded and distributed uniformly by the host; dynamic plugin backends return message keys, parameters, fallback text, or raw business data.
  • Translation keys should be stable. Plugin business copy, notification titles, and audit text should use stable keys and provide readable fallback text.
  • Search capability is for admin filtering. FindMessageKeys is suited for log filtering, API documentation filtering, and similar scenarios, and should not be used in high-frequency request paths.