diff --git a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/pluggable-widgets/pluggable-widgets-client-apis/_index.md b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/pluggable-widgets/pluggable-widgets-client-apis/_index.md index 61cea9d87ac..fc8085394c1 100644 --- a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/pluggable-widgets/pluggable-widgets-client-apis/_index.md +++ b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/pluggable-widgets/pluggable-widgets-client-apis/_index.md @@ -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 + + + Greeting + + Hello, World! + Hallo, Wereld! + + + +``` + +```tsx +export function MyWidget({ texts }: MyWidgetContainerProps) { + return

{texts.translate("greeting")}

; +} +``` + +{{% 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 + + + Import Summary + + Successfully imported {2} records. {1} records had errors. + {2} Rijen zijn succesvol geïmporteerd. {1} Rijen hadden foutmeldingen. + + + + + + + +``` + +```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} + + + + Greeting + + + + + + + + +``` + +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} diff --git a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/pluggable-widgets/pluggable-widgets-property-types.md b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/pluggable-widgets/pluggable-widgets-property-types.md index 8b95f012807..aa4326fcd53 100644 --- a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/pluggable-widgets/pluggable-widgets-property-types.md +++ b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/pluggable-widgets/pluggable-widgets-property-types.md @@ -966,6 +966,117 @@ The editability property allows a pluggable widget to have an editable configura ``` +### 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 `` 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 `` element defines the caption used in Studio Pro. + +###### Translations + +The `` element takes a list of `` 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 `` element takes a list of `` 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 `` element declares a set of texts that the widget uses which belong to a different namespace. + +By adding `` elements as children, the set of texts is restricted to those texts. If no `` 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 + + + + + + + +``` + +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 `` element represents a single translatable string that belongs to the namespace defined by ``. + +| Attribute | Required | Attribute Type | Description | +|----------------|----------|---------------------|---------------------------------------------------------------------------------------------------------------------------------| +| `key` | Yes | String | Identifier of the text. | + +#### Studio Pro UI + +When the property is defined as follows: + +```xml + + + Greeting + + Welcome, {1}! + Welkom, {1}! + + + + + + + Notification Count + + You have {1} unread notifications. + Je hebt {1} ongelezen berichten. + + + + + + + + + + +``` + +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" >}} + +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: diff --git a/content/en/docs/refguide/modeling/pages/common-widget-properties.md b/content/en/docs/refguide/modeling/pages/common-widget-properties.md index 4056186ffc9..fcfeb016355 100644 --- a/content/en/docs/refguide/modeling/pages/common-widget-properties.md +++ b/content/en/docs/refguide/modeling/pages/common-widget-properties.md @@ -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" >}}