Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(plugins): document the configUi locale field

Yudhi Armyndharis173c088b010a
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d1b5333b6..9c1f47289 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
+### Fixed
+
+- A plugin `configUi` editor receives the dashboard language as `locale` in `config:value`, and the `schema` it gets carries field titles and descriptions localized from the manifest `i18n` block, as the generated form already showed. Thanks @probably-ABHINAV, and @TreIngenia for the proposal.
+
## [0.23.7] - 2026-09-25
### Added
diff --git a/dashboard/src/pages/Plugins.tsx b/dashboard/src/pages/Plugins.tsx
index 3884f00d9..e2fff3b10 100644
--- a/dashboard/src/pages/Plugins.tsx
+++ b/dashboard/src/pages/Plugins.tsx
@@ -237,7 +237,7 @@ function ConfigField({
* to 'self'/data: and forbids connections/forms — see utils/pluginFrameSecurity), and injected
* as `srcdoc` into a `sandbox="allow-scripts"` iframe (opaque origin — no access to the parent).
* The editor talks to the host over a postMessage bridge:
- * iframe → host { type: 'config:get' } → host → iframe { type: 'config:value', config, schema, theme }
+ * iframe → host { type: 'config:get' } → host → iframe { type: 'config:value', config, schema, locale, theme }
* iframe → host { type: 'config:save', config } → host → iframe { type: 'config:saved' } | { type: 'config:error', message }
* The host makes the authenticated PUT (secret redact/restore applies); the iframe only ever sees the
* already-redacted config.
@@ -247,8 +247,13 @@ function ConfigField({
* which is how the Chat Flow editor ended up a glaring white panel inside a dark modal. Additive: an
* editor that ignores the field renders exactly as it did before.
*
- * Sending it once, with the handshake, is sufficient: the theme control sits behind the modal overlay,
- * so the theme cannot change while an editor is open, and reopening re-runs the handshake.
+ * `locale` is the dashboard language code ('es', 'zh-CN', ...), and `schema` arrives with field titles and
+ * descriptions localized from the manifest `i18n` block, the same text the generated form shows. The
+ * iframe cannot read the parent's language setting either, and the manifest block covers only top-level
+ * field text, so `locale` is what lets an editor translate its own strings. Additive, like `theme`.
+ *
+ * Sending them once, with the handshake, is sufficient: the theme and language controls sit behind the
+ * modal overlay, so neither can change while an editor is open, and reopening re-runs the handshake.
*/
function PluginConfigUi({ plugin, sessionId }: { plugin: Plugin; sessionId?: string }) {
const { t, i18n } = useTranslation();
diff --git a/docs/19-plugin-architecture.md b/docs/19-plugin-architecture.md
index b4e4c6805..92b533e4f 100644
--- a/docs/19-plugin-architecture.md
+++ b/docs/19-plugin-architecture.md
@@ -171,17 +171,17 @@ a host version, except for the SDK-major check applied to a manifest that declar
| `configUi` | — | Optional self-contained HTML config editor served into a sandboxed iframe. When present it **replaces** the generated form and owns saving — the dashboard renders neither the form nor its Save button |
| `hooks` | — | Hook events this plugin listens to (informational) |
| `provides` / `requires` | — | Features this plugin provides / depends on |
-| `i18n` | — | Localized dashboard text per locale (dashboard-only) |
+| `i18n` | — | Localized dashboard text per locale (dashboard-only; a `configUi` editor receives it through the localized `schema`) |
**The `configUi` bridge.** The editor is injected as `srcdoc` into a `sandbox="allow-scripts"` iframe, so
it has an opaque origin and no access to the dashboard. It talks to the host by `postMessage`:
-| Direction | Message | Notes |
-| ------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
-| iframe → host | `{ type: 'config:get' }` | Sent on load; the host answers with the current values |
-| host → iframe | `{ type: 'config:value', config, schema, theme }` | `config` is already secret-redacted. `theme` is `'light'` or `'dark'`, resolved by the host |
-| iframe → host | `{ type: 'config:save', config }` | The host makes the authenticated write |
-| host → iframe | `{ type: 'config:saved' }` / `{ type: 'config:error', message }` | Outcome of that write |
+| Direction | Message | Notes |
+| ------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| iframe → host | `{ type: 'config:get' }` | Sent on load; the host answers with the current values |
+| host → iframe | `{ type: 'config:value', config, schema, locale, theme }` | `config` is already secret-redacted. `schema` text is localized for `locale`, the dashboard language. `theme` is `'light'` or `'dark'`, resolved by the host |
+| iframe → host | `{ type: 'config:save', config }` | The host makes the authenticated write |
+| host → iframe | `{ type: 'config:saved' }` / `{ type: 'config:error', message }` | Outcome of that write |
`theme` matters because an opaque-origin iframe cannot read the dashboard's theme for itself; without it
an editor can only guess, and a light-only editor becomes a glaring white panel inside a dark modal. It is
@@ -189,6 +189,14 @@ sent once, with the handshake — the theme control sits behind the modal overla
change while an editor is open. Treat it as optional: an editor that ignores it still works, and one that
uses it should fall back to `prefers-color-scheme` so it stays readable on an older host.
+`locale` is the dashboard's language code (`'es'`, `'zh-CN'`, ...), sent for the same reason: the iframe
+cannot read the operator's language setting, and `navigator.language` differs from it whenever the
+operator picked a language other than the browser's. The `schema` in the same message carries field
+titles and descriptions localized from the manifest `i18n` block for that code, the same text the
+generated form shows. Everything else in the editor (its own labels, buttons, messages) is the editor's
+to translate from `locale`. Treat it as optional too, and fall back to `navigator.language` on an older
+host.
+
A `configSchema` field may set `secret: true` (e.g. an API key): the value is masked on read and
preserved on an unchanged write.