Skip to content

[WTF-2628]: Document widget System Texts #11901

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
weirdwater wants to merge 3 commits into
base: development
Choose a base branch
from
Draft

[WTF-2628]: Document widget System Texts #11901

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5a7e943
Document widget System Texts
weirdwater Sep 9, 2026
9fe4cc2
QA: Correct parameters example
weirdwater Sep 11, 2026
2a6423b
QA: Use consistent image alt text
weirdwater Sep 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 94 additions & 0 deletions ...apidocs/studio-pro-11/pluggable-widgets/pluggable-widgets-client-apis/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -483,6 +483,100 @@ if (selection.type === "Single") {
}
```

### SystemTextsValue {#systemtexts}

The `SystemTextsValue` exposes the `translate()` function which allows widgets to use [system texts](/refguide/system-texts/). When a widget declares that it uses system texts, the value is available under the `texts` prop.

```ts
interface SystemTextsValue {
readonly translate(key: string, parameters?: string[]): string;
readonly translate(namespace: string, key: string, parameters?: string[]): string;
}
```

Widgets declare the use of system texts by adding the [Text system property](/apidocs-mxsdk/apidocs/pluggable-widgets-property-types/#text) and defining their own texts or referencing external texts. Widgets written in TypeScript provide type checking for `translate()` to ensure correct use of the texts.

```xml
<systemProperty key="Text">
<text key="greeting">
<caption>Greeting</caption>
<translations>
<translation lang="en_US">Hello, World!</translation>
<translation lang="nl_NL">Hallo, Wereld!</translation>
</translations>
</text>
</systemProperty>
```

```tsx
export function MyWidget({ texts }: MyWidgetContainerProps) {
return <h1>{texts.translate("greeting")}</h1>;
}
```

{{% alert color="info" %}}
Currently, you can only provide default translations in English (`en_US`) and Dutch (`nl_NL`).
{{% /alert %}}

#### Parameters

System texts may be parameterized to allow for dynamic translations.

Parameters are _positional_ and are passed as an _array of strings_ to `translate()`.

```xml
<systemProperty key="Text">
<text key="import_summary">
<caption>Import Summary</caption>
<translations>
<translation lang="en_US">Successfully imported {2} records. {1} records had errors.</translation>
<translation lang="nl_NL">{2} Rijen zijn succesvol geïmporteerd. {1} Rijen hadden foutmeldingen.</translation>
</translations>
<parameters>
<parameter caption="Count Errors" />
<parameter caption="Count Successful" />
</parameters>
</text>
</systemProperty>
```

```ts
translate("import_summary", [ errorCount.toString(), successCount.toString() ])
```

Widgets written in TypeScript report missing parameters for texts defined by the widget.

#### Sharing System Texts {#external-texts}

By declaring external texts, a widget can use texts from other namespaces. Each system text belongs to a namespace, and texts defined by a widget have the widget's ID as their namespace.

To use a text from widget A, widget B must declare it as an external text with the ID of widget A as the namespace.

```xml {hl_lines=6}
<!-- widget id: example.widgetb.widgetB -->
<systemProperty key="Text">
<text key="greeting">
<caption>Greeting</caption>
</text>
<externalTexts namespace="example.widgeta.widgetA">
<text key="import_summary" />
</externalTexts>
<externalTexts namespace="mxui.common">
<text key="true" />
</externalTexts>
</systemProperty>
```

The `translate()` method takes a namespace and a key as parameters to use a specific text. When the namespace is not specified, the method assumes that the key belongs to the namespace of the current widget. You can refer to any system text available in the app.

```tsx
translate("greeting") // example.widgetb.widgetB.greeting
translate("example.widgeta.widgetA", "import_summary", [ "4", "2" ]) // example.widgeta.widgetA.import_summary
translate("mxui.common", "true") // mxui.common.true
```

Parameters may be passed to external texts. Note that there is no type checking for the parameters of external texts.

## Exposed Modules

### Session {#session}
Expand Down
111 changes: 111 additions & 0 deletions ...sdk/apidocs/studio-pro-11/pluggable-widgets/pluggable-widgets-property-types.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -966,6 +966,117 @@ The editability property allows a pluggable widget to have an editable configura
<systemProperty key="Editability"/>
```

### Text {#text}

The system text property allows a pluggable widget to define and use translatable texts. The translations are made available through a `texts` property added to the widget's container props with a [SystemTextsValue](/apidocs-mxsdk/apidocs/pluggable-widgets-client-apis/#systemtexts).

The widget may define [its own texts](#widget-texts), or declare the use of [external texts](#external-texts).

#### XML Elements

##### Text {#widget-texts}

A `<text>` element represents a single translatable string. Each text is identified by its `key` attribute.

| Attribute | Required | Attribute Type | Description |
|----------------|----------|---------------------|---------------------------------------------------------------------------------------------------------------------------------|
| `key` | Yes | String | Identifier of the text. |

###### Caption

The `<caption>` element defines the caption used in Studio Pro.

###### Translations

The `<translations>` element takes a list of `<translation>` elements, which define the default translations for the text.

| Attribute | Required | Attribute Type | Description |
|----------------|----------|---------------------|---------------------------------------------------------------------------------------------------------------------------------|
| `lang` | Yes | String | Code of the language for the translation. Must be one of `en_US`, or `nl_NL`. |

###### Parameters

The `<parameters>` element takes a list of `<parameter>` elements. Each parameter defines a variable that can be used in the text.

System text parameters are positional. Numbered placeholders indicate where the parameter is substituted in a translation. For example, `{2}` would get substituted by the value of the second parameter. Parameter values are [passed by the widget](/apidocs-mxsdk/apidocs/pluggable-widgets-client-apis/#parameters).

| Attribute | Required | Attribute Type | Description |
|----------------|----------|---------------------|---------------------------------------------------------------------------------------------------------------------------------|
| `caption` | Yes | String | Caption of the parameter. Displayed in Studio Pro and used to generate types for the `translate()` method. |

##### External Texts {#external-texts}

The `<externalTexts>` element declares a set of texts that the widget uses which belong to a different namespace.

By adding `<text>` elements as children, the set of texts is restricted to those texts. If no `<text>` elements are added, the full namespace is imported for the widget. The benefit of restricting the set of texts is more precise type and consistency checking.

```xml
<systemProperty key="Text">
<externalTexts namespace="example.widgeta.widgetA" />
<externalTexts namespace="example.widgetb.widgetB">
<text key="greeting" />
<text key="goodbye" />
</externalTexts>
</systemProperty>
```

The example above would import all texts from the `example.widgeta.widgetA` namespace, but only the texts `greeting` and `goodbye` from the `example.widgetb.widgetB` namespace.

| Attribute | Required | Attribute Type | Description |
|----------------|----------|---------------------|---------------------------------------------------------------------------------------------------------------------------------|
| `namespace` | Yes | String | Identifier of the namespace. May be any system text namespace, including other widget IDs. |

###### Text

A `<text>` element represents a single translatable string that belongs to the namespace defined by `<externalTexts>`.

| Attribute | Required | Attribute Type | Description |
|----------------|----------|---------------------|---------------------------------------------------------------------------------------------------------------------------------|
| `key` | Yes | String | Identifier of the text. |

#### Studio Pro UI

When the property is defined as follows:

```xml
<systemProperty key="Text">
<text key="greeting">
<caption>Greeting</caption>
<translations>
<translation lang="en_US">Welcome, {1}!</translation>
<translation lang="nl_NL">Welkom, {1}!</translation>
</translations>
<parameters>
<parameter caption="Username" />
</parameters>
</text>
<text key="notification_count">
<caption>Notification Count</caption>
<translations>
<translation lang="en_US">You have {1} unread notifications.</translation>
<translation lang="nl_NL">Je hebt {1} ongelezen berichten.</translation>
</translations>
<parameters>
<parameter caption="Count" />
</parameters>
</text>
<externalTexts namespace="mxui.common">
<text key="true" />
<text key="false" />
</externalTexts>
</systemProperty>
```

Then the Studio Pro UI for the property appears like this:

{{< figure src="/attachments/apidocs-mxsdk/apidocs/pluggable-widgets/pluggable-widgets-property-types/widget-system-texts-properties-dialog.png" alt="The Studio Pro properties dialog box showing the widget's system texts" class="no-border" >}}
Comment thread
weirdwater marked this conversation as resolved.

Note that external texts are not listed.

Clicking **Go to system texts** opens the system texts editor, where the texts appear categorized under the widget's name:

{{< figure src="/attachments/apidocs-mxsdk/apidocs/pluggable-widgets/pluggable-widgets-property-types/widget-system-texts-editor.png" alt="The system texts editor showing the widget's texts categorized under the widget's name" class="no-border" >}}

## Converting Properties {#converting-properties}

When a pluggable widget's property type changes, the Mendix Platform will automatically migrate the value of the property to the new type. The following table lists the property type changes that are supported:
Expand Down
6 changes: 6 additions & 0 deletions content/en/docs/refguide/modeling/pages/common-widget-properties.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,12 @@ Dynamic classes do not require a data container.

Some widgets, for example snippets and building blocks, have a **Documentation** property which can be used to store developer documentation. This can be used to explain to other developers how to use these widgets. End-users will never see this documentation.

### Texts {#texts}

Widgets that include translatable texts display an overview of their [system texts](/refguide/system-texts/). To manage the translations, click **Go to system texts** to open the system text editor.

{{< figure src="/attachments/apidocs-mxsdk/apidocs/pluggable-widgets/pluggable-widgets-property-types/widget-system-texts-properties-dialog.png" alt="The Studio Pro properties dialog box showing the widget's system texts" class="no-border" >}}

## Data Source Section{#data-source}

{{< figure src="/attachments/refguide/modeling/pages/common-widget-properties/data-source-section.png" alt="Data Source Section" class="no-border" >}}
Expand Down
Loading