HowToTranslateAnApp

How to translate an app

To show how we can use I18n in our Open Pioneer Trails apps, we will extend the empty app (at src/apps/empty).

By default, the empty app is prepared to support I18n with locale en. We will add support for another language (locale de) and demonstrate advanced features of FormatJS (opens in a new tab) Intl.

Note
For more details to I18n file format please check I18nFormat.

Preparing i18n support for our app

To begin, start the development server

1
pnpm run dev

and open the empty app (opens in a new tab)

Open the build.config.mjs and add locale de to the i18n property:

1
import { defineBuildConfig } from "@open-pioneer/build-support";
2

3
export default defineBuildConfig({
4
    i18n: ["de", "en"]
5
});

We will see an error message in browser, because of the missing yaml file for our new locale. We need to create the file in the i18n folder. The naming schema of the file is {locale}.yaml.

1
messages:
2
    heading: "I18n HowTo"
3
    text: "Wie lässt sich I18n in Open Pioneer Trails Apps nutzen?"

By default, the app uses the browser settings or system default for determining the locale. If your browser locale is set to de you should see the values from de.yaml (maybe you will need to restart the dev server).

i18n howto app

To demonstrate the multi-language support and force a language of our choice, we need to modify the app.ts:

1
import { createCustomElement } from "@open-pioneer/runtime";
2
import * as appMetadata from "open-pioneer:app";
3
import { AppUI } from "./AppUI";
4

5
// Reads the 'lang' parameter from the URL and, if set, uses it
6
// for the application's locale.
7
// This can be helpful during development, but it is entirely optional.
8
const URL_PARAMS = new URLSearchParams(window.location.search);
9
const FORCED_LANG = URL_PARAMS.get("lang") || undefined;
10

11
const Element = createCustomElement({
12
    component: AppUI,
13
    appMetadata,
14
    config: {
15
        // Forces the locale if set to a string.
16
        // 'undefined' choses an automatic locale based on the app and
17
        // the user's preferred languages.
18
        locale: FORCED_LANG
19
    }
20
});
21
customElements.define("empty-app", Element);

Now we are able to force the locale with lang parameter: http://localhost:5173/sites/empty/?lang=de (opens in a new tab) or http://localhost:5173/sites/empty/?lang=en (opens in a new tab)

Note The integration of I18n works the same way for Trails packages. We have to add the i18n configuration in build.config.mjs and matching yaml files for each language in the i18n folder. For each app/language combination, the build tool collects the YAML files of the app and the used packages and merges them into a flattened JSON structure. As mentioned in I18nFormat we can override yaml entries from packages in our app yaml. Please check the i18n-sample (opens in a new tab) app as a practical example for this topic.

Using advanced features of FormatJS Intl

In a first step we prepare our AppUI:

1
export function AppUI() {
2
    const intl = useIntl();
3
    return (
4
        <Container>
5
            <Heading as="h1" size="lg">
6
                {intl.formatMessage({ id: "heading" })}
7
            </Heading>
8
            <Text>{intl.formatMessage({ id: "text" })}</Text>
9
            <ExampleStack></ExampleStack>
10
        </Container>
11
    );
12
}

We initialize the intl object with the useIntl hook. Now we can use intl.formatMessage with our flattened keys from the yaml files to add our translated text to the app. In addition, we define the ExampleStack as a container for our advanced examples.

Interpolation

First we generate an entry in our ExampleStack for our InterpolationExample:

1
function ExampleStack() {
2
    return (
3
        <Stack mb={5} mt={5} gap="24px" align="stretch">
4
            <StackSeparator borderColor="gray.200" />
5
            <Box bg="white" w="100%" p={4} color="black" borderWidth="1px" borderColor="black">
6
                <InterpolationExample></InterpolationExample>
7
            </Box>
8
        </Stack>
9
    );
10
}

Interpolation allows replacement with dynamic values. That’s why we use a text input field in our interpolation example:

1
function InterpolationExample() {
2
    const intl = useIntl();
3
    const [value, setValue] = useState("");
4
    return (
5
        <>
6
            <Heading as="h4" size="md">
7
                {intl.formatMessage({ id: "interpolation.heading" })}
8
            </Heading>
9
            <Input
10
                value={value}
11
                onChange={(evt) => setValue(evt.target.value)}
12
                placeholder={intl.formatMessage({ id: "interpolation.placeholder" })}
13
                size="sm"
14
            />
15
            <Text mb="8px">
16
                {intl.formatMessage({ id: "interpolation.value" }, { name: value })}
17
            </Text>
18
        </>
19
    );
20
}

As we can see, the bound input value value is passed to the intl.formatMessage function with the parameter name name. Add the keys and values to the yaml configuration:

1
messages:
2
    #....
3
    interpolation:
4
        heading: "Beispiel für Interpolation (dynamische Werte)"
5
        value: "Hallo {name}"
6
        placeholder: "Geben Sie Ihren Namen ein..."
7
#....

Add the defined keys to all yaml files.

The interpolation.value key uses a placeholder for name. In the rendered text the passed value of name will replace the placeholder.

interplation example

Plurals

We generate another entry in our ExampleStack for our PluralsExample:

1
function ExampleStack() {
2
    return (
3
        <Stack
4
            mb={5}
5
            mt={5}
6
            separator={<StackSeparator borderColor="gray.200" />}
7
            gap="24px"
8
            align="stretch"
9
        >
10
            <Box bg="white" w="100%" p={4} color="black" borderWidth="1px" borderColor="black">
11
                <InterpolationExample></InterpolationExample>
12
            </Box>
13
            <Box bg="white" w="100%" p={4} color="black" borderWidth="1px" borderColor="black">
14
                <PluralsExample></PluralsExample>
15
            </Box>
16
        </Stack>
17
    );
18
}

With plural support we can output different text depending on a count value (see Link (opens in a new tab)). We will use a RadioGroup to change the count value in our example:

1
function PluralsExample() {
2
    const intl = useIntl();
3
    const [value, setValue] = useState<string | null>("1");
4
    return (
5
        <>
6
            <Heading as="h4" size="md">
7
                {intl.formatMessage({ id: "plurals.heading" })}
8
            </Heading>
9
            {/*import { Radio, RadioGroup } from "@open-pioneer/chakra-snippets/radio";*/}
10
            <RadioGroup onValueChange={(e) => setValue(e.value)} value={value}>
11
                <Stack gap={4} direction="row">
12
                    <Radio value="0">0</Radio>
13
                    <Radio value="1">1</Radio>
14
                    <Radio value="42">42</Radio>
15
                    <Radio value="99">99</Radio>
16
                </Stack>
17
            </RadioGroup>
18
            <Text mb="8px">{intl.formatMessage({ id: "plurals.value" }, { n: value })}</Text>
19
        </>
20
    );
21
}

The bound value value is passed to the intl.formatMessage function with the parameter name n. Here is the yaml configuration:

1
messages:
2
    #....
3
    plurals:
4
        heading: "Beispiel für Plural"
5
        value: "Wir trinken {n, plural, =0 {kein Bier} one {ein Bier} other {# Biere} =99 {zu viel Bier}}"
6
#....

Add the defined keys to all yaml files.

The plurals.value key defines a count parameter n. In result the passed value of n will be used to generate the matching output.

plurals example

Selection

Let’s add an entry for SelectionExample in our ExampleStack:

1
function ExampleStack() {
2
    return (
3
        <Stack
4
            mb={5}
5
            mt={5}
6
            separator={<StackSeparator borderColor="gray.200" />}
7
            gap="24px"
8
            align="stretch"
9
        >
10
            <Box bg="white" w="100%" p={4} color="black" borderWidth="1px" borderColor="black">
11
                <InterpolationExample></InterpolationExample>
12
            </Box>
13
            <Box bg="white" w="100%" p={4} color="black" borderWidth="1px" borderColor="black">
14
                <PluralsExample></PluralsExample>
15
            </Box>
16
            <Box bg="white" w="100%" p={4} color="black" borderWidth="1px" borderColor="black">
17
                <SelectionExample></SelectionExample>
18
            </Box>
19
        </Stack>
20
    );
21
}

With selection support we can output different text depending on a set of given values (see Link (opens in a new tab)). In our example we will change the title depending on a gender selection. We will use a text input for name and a RadioGroup for gender selection:

1
function SelectionExample() {
2
    const intl = useIntl();
3
    const [value1, setValue1] = useState("");
4
    const [value2, setValue2] = useState<string | null>("male");
5
    return (
6
        <>
7
            <Heading as="h4" size="md">
8
                {intl.formatMessage({ id: "selection.heading" })}
9
            </Heading>
10
            <Input
11
                value={value1}
12
                onChange={(evt) => setValue1(evt.target.value)}
13
                placeholder={intl.formatMessage({ id: "interpolation.placeholder" })}
14
                size="sm"
15
            />
16
            <RadioGroup onValueChange={(e) => setValue2(e.value)} value={value2}>
17
                <Stack gap={4} direction="row">
18
                    <Radio value="female">
19
                        {intl.formatMessage({ id: "selection.gender.female" })}
20
                    </Radio>
21
                    <Radio value="male">
22
                        {intl.formatMessage({ id: "selection.gender.male" })}
23
                    </Radio>
24
                    <Radio value="other">
25
                        {intl.formatMessage({ id: "selection.gender.other" })}
26
                    </Radio>
27
                </Stack>
28
            </RadioGroup>
29
            <Text mb="8px">
30
                {intl.formatMessage({ id: "selection.value" }, { name: value1, gender: value2 })}
31
            </Text>
32
        </>
33
    );
34
}

We pass the name (value1) and gender (value2) to the intl.formatMessage. Here is the yaml configuration:

1
messages:
2
    #....
3
    selection:
4
        heading: "Beispiel für Selektion"
5
        value: "{gender, select, male {Herr} female {Frau} other {}} {name}"
6
        gender:
7
            male: "männlich"
8
            female: "weiblich"
9
            other: "divers"
10
#....

Add the defined keys to all yaml files.

The selection.value key defines a parameter gender for selection and uses the dynamic parameter name. In a selection we always have to define the other parameter. It is used if the given parameter value does not match one of the other values (e.g. male or female). In result the passed value of gender and name will be used to generate the matching output.

selection example

Number Format

Now we add an entry for NumberFormatExample to our ExampleStack :

1
function ExampleStack() {
2
    return (
3
        <Stack
4
            mb={5}
5
            mt={5}
6
            separator={<StackSeparator borderColor="gray.200" />}
7
            gap="24px"
8
            align="stretch"
9
        >
10
            <Box bg="white" w="100%" p={4} color="black" borderWidth="1px" borderColor="black">
11
                <InterpolationExample></InterpolationExample>
12
            </Box>
13
            <Box bg="white" w="100%" p={4} color="black" borderWidth="1px" borderColor="black">
14
                <PluralsExample></PluralsExample>
15
            </Box>
16
            <Box bg="white" w="100%" p={4} color="black" borderWidth="1px" borderColor="black">
17
                <SelectionExample></SelectionExample>
18
            </Box>
19
            <Box bg="white" w="100%" p={4} color="black" borderWidth="1px" borderColor="black">
20
                <NumberFormatExample></NumberFormatExample>
21
            </Box>
22
        </Stack>
23
    );
24
}

With formatNumber we can not only format numbers locale specific, but also use units and currencies (see Link (opens in a new tab)). In our example we will have a number input and an output with different forms of unit and currency:

1
function NumberFormatExample() {
2
    const intl = useIntl();
3
    const [value, setValue] = useState("424224.24");
4
    return (
5
        <>
6
            <Heading as="h4" size="md">
7
                {intl.formatMessage({ id: "numberformat.heading" })}
8
            </Heading>
9
            {/*import { NumberInputField, NumberInputRoot } from "@open-pioneer/chakra-snippets/number-input";*/}
10
            <NumberInputRoot
11
                onValueChange={(valueChangeDetails) => {
12
                    setValue(valueChangeDetails.value);
13
                }}
14
                value={value}
15
                step={0.25}
16
                formatOptions={{
17
                    minimumFractionDigits: 2,
18
                    maximumFractionDigits: 2,
19
                    useGrouping: false
20
                }}
21
            >
22
                <NumberInputField />
23
            </NumberInputRoot>
24
            <Text mb="8px">
25
                {intl.formatMessage({ id: "numberformat.example.currency1" })}
26
                {intl.formatNumber(+value, { style: "currency", currency: "EUR" })}
27
            </Text>
28
            <Text mb="8px">
29
                {intl.formatMessage({ id: "numberformat.example.currency2" })}
30
                {intl.formatNumber(+value, {
31
                    style: "currency",
32
                    currency: "EUR",
33
                    currencyDisplay: "name"
34
                })}
35
            </Text>
36
            <Text mb="8px">
37
                {intl.formatMessage({ id: "numberformat.example.unit1" })}
38
                {intl.formatNumber(+value, { style: "unit", unit: "terabyte-per-second" })}
39
            </Text>
40
            <Text mb="8px">
41
                {intl.formatMessage({ id: "numberformat.example.unit2" })}
42
                {intl.formatNumber(+value, {
43
                    style: "unit",
44
                    unit: "terabyte-per-second",
45
                    unitDisplay: "long"
46
                })}
47
            </Text>
48
        </>
49
    );
50
}

Here is the yaml configuration:

1
messages:
2
    #....
3
    numberformat:
4
        heading: "Beispiele für NumberFormat"
5
        example:
6
            currency1: "Währung (Symbol): "
7
            currency2: "Währung (lang): "
8
            unit1: "Maßeinheiten (kurz): "
9
            unit2: "Maßeinheiten (lang): "
10
#....

Add the defined keys to all yaml files.

We pass the value with different NumberFormatOptions to intl.formatNumber. In result, we see our formatted numbers.

number format example

Date/Time Format and Relative Time Format

Finally, we add an entry for the DateTimeFormatExample to our ExampleStack :

1
function ExampleStack() {
2
    return (
3
        <Stack
4
            mb={5}
5
            mt={5}
6
            separator={<StackSeparator borderColor="gray.200" />}
7
            gap="24px"
8
            align="stretch"
9
        >
10
            <Box bg="white" w="100%" p={4} color="black" borderWidth="1px" borderColor="black">
11
                <InterpolationExample></InterpolationExample>
12
            </Box>
13
            <Box bg="white" w="100%" p={4} color="black" borderWidth="1px" borderColor="black">
14
                <PluralsExample></PluralsExample>
15
            </Box>
16
            <Box bg="white" w="100%" p={4} color="black" borderWidth="1px" borderColor="black">
17
                <SelectionExample></SelectionExample>
18
            </Box>
19
            <Box bg="white" w="100%" p={4} color="black" borderWidth="1px" borderColor="black">
20
                <NumberFormatExample></NumberFormatExample>
21
            </Box>
22
            <Box bg="white" w="100%" p={4} color="black" borderWidth="1px" borderColor="black">
23
                <DateTimeFormatExample></DateTimeFormatExample>
24
            </Box>
25
        </Stack>
26
    );
27
}

In our example we will have a date time input:

1
function DateTimeFormatExample() {
2
    const intl = useIntl();
3
    const [value, setValue] = useState("2023-02-19T19:02");
4
    return (
5
        <>
6
            <Heading as="h4" size="md">
7
                {intl.formatMessage({ id: "datetimeformat.heading" })}
8
            </Heading>
9
            <Input
10
                value={value}
11
                onChange={(evt) => setValue(evt.target.value)}
12
                size="md"
13
                type="datetime-local"
14
            />
15
            <Text mb="8px">
16
                {intl.formatMessage({ id: "datetimeformat.timelabel" })}
17
                {intl.formatDate(value, { dateStyle: "full", timeStyle: "short" })}
18
            </Text>
19
            <Text mb="8px">
20
                {intl.formatMessage({ id: "datetimeformat.relativetimelabel" })}
21
                {intl.formatRelativeTime(getDeltaTime(value), "minute", {
22
                    numeric: "auto",
23
                    style: "long"
24
                })}
25
            </Text>
26
        </>
27
    );
28
}

To calculate the delta for our relative time output we define the function getDeltaTime:

1
function getDeltaTime(datetime: string): number {
2
    const delta = new Date(datetime).getTime() - new Date().getTime();
3
    return Math.round(delta / 60000);
4
}

Here is the yaml configuration:

1
messages:
2
    #....
3
    datetimeformat:
4
        heading: "Beispiel DateTimeFormat"
5
        timelabel: "Der gewählte Zeitpunkt ist "
6
        relativetimelabel: "Relative Zeit zum gewählten Zeitpunkt: "
7
#....

Add the defined keys to all yaml files.

We pass the value with DateTimeFormatOptions to intl.formatDate (see Link (opens in a new tab)) and with RelativeTimeFormatOptions to intl.formatRelativeTime (see Link (opens in a new tab))

In result, we see our selected formatted datetime and the relative time between now and the selected datetime.

datetime format example

Note
The used datetime input does not support a forced locale. It always uses the defined browser locale or the system default. In our example, if your browser uses locale de but your app uses url parameter lang=en the input will show values matching to locale de.

Formatting rich text

So far, we have used the intl.formatMessage method to format strings. Using this function, primitive values (such as strings, numbers, etc.) can be used as values in placeholders such as {name}. For rich user interfaces, this way of rendering messages can be limiting in practice.

To render rich text with React components for your user interface, use intl.formatRichMessage() instead. This functions follows the same principles as intl.formatMessage(), but is different in a few key ways:

It always returns a React node. This makes it very powerful, but this also means that it can only be used in combination with React components.
It supports React nodes as values. You can still use placeholders in your messages (like {name}) but you can substitute arbitrary React nodes instead of only primitive values.
It supports defining custom tags in terms of React nodes, using functions as values.
It provides a few basic formatting tags out of the box.

Examples:

Our messages look similar to the earlier examples:

1
messages:
2
    # ...
3
    richtext:
4
        heading: "Beispiel für Rich Text"
5
        messageWithReactNode: "Dieser Text enthält (hier: {element}) ein beliebiges React-Element."
6
        messageWithInlineCode: "Dieser Text enthält <code>inline code</code>."
7
        messageWithReactTag: "Dieser Text verwendet <customTag>einen Tag, der über React-Elemente definiert ist.</customTag>"

It is the rendering part that differs:

1
function RichTextExample() {
2
    const intl = useIntl();
3

4
    return (
5
        <>
6
            <Heading as="h4" size="md">
7
                {intl.formatMessage({ id: "richtext.heading" })}
8
            </Heading>
9
            <VStack gap={2} align="start">
10
                <Box>
11
                    {intl.formatRichMessage(
12
                        { id: "richtext.messageWithReactNode" },
13
                        {
14
                            element: (
15
                                <Tag.Root>
16
                                    <Tag.Label>Hi</Tag.Label>
17
                                </Tag.Root>
18
                            )
19
                        }
20
                    )}
21
                </Box>
22
                <Box>
23
                    {intl.formatRichMessage({
24
                        id: "richtext.messageWithInlineCode"
25
                    })}
26
                </Box>
27
                <Box>
28
                    {intl.formatRichMessage(
29
                        {
30
                            id: "richtext.messageWithReactTag"
31
                        },
32
                        {
33
                            customTag: (parts) => (
34
                                <Box display="inline-block" background="trails.200" px={1}>
35
                                    {parts}
36
                                </Box>
37
                            )
38
                        }
39
                    )}
40
                </Box>
41
            </VStack>
42
        </>
43
    );
44
}

The code above is rendered like this:

rich text example

Using i18n in a service

The intl object is not only available in React components, it can also be used from any service. The GreetingService in the following example uses the serviceOptions parameter (provided by the framework) to access the package’s intl object via currentIntl. This object can be used in the same way as the intl object returned by useIntl:

1
import { type DECLARE_SERVICE_INTERFACE, ServiceOptions, PackageIntl } from "@open-pioneer/runtime";
2

3
export class GreetingService {
4
    declare [DECLARE_SERVICE_INTERFACE]: "i18n-howto-app.GreetingService";
5

6
    private readonly _intl: ReadonlyReactive<PackageIntl>;
7

8
    constructor(serviceOptions: ServiceOptions) {
9
        this._intl = serviceOptions.currentIntl;
10
    }
11

12
    // (1)
13
    greet(name: string): string {
14
        return this._intl.value.formatMessage({ id: "greetingService.greeting" }, { name });
15
    }
16
}

Our goal is to implement a UI component that calls the greet() (see (1)) method from above. To make the service usable from the UI, we have to perform some necessary plumbing:

1
export { GreetingService } from "./GreetingService";

1
import { defineBuildConfig } from "@open-pioneer/build-support";
2

3
export default defineBuildConfig({
4
    i18n: ["de", "en"],
5
    services: {
6
        GreetingService: {
7
            provides: ["i18n-howto-app.GreetingService"]
8
        }
9
    },
10
    ui: {
11
        references: ["i18n-howto-app.GreetingService"]
12
    }
13
});

Here is the yaml configuration:

1
messages:
2
    #....
3
    serviceI18n:
4
        heading: "Beispiel für Service I18n"
5
        placeholder: "Namen eintragen"
6
        showGreeting: "Nachricht anzeigen"
7
        serviceResponse: "Nachricht: "
8
    greetingService:
9
        greeting: Hallo {name}!
10
#....

The ServiceI18nExample component displays a plain and simple react form using the intl API you have already seen. In addition to using i18n from within the React component, it also interacts with a service (GreetingService, (1) in the example below) to show a translated message. The form simply asks the user for a name and then calls the greetingService.greet(name) method (see (2) below) to show a greeting:

1
function ServiceI18nExample() {
2
    const intl = useIntl();
3
    const greetingService = useService<GreetingService>("i18n-howto-app.GreetingService");
4
    const [inputValue, setInputValue] = useState("");
5
    const [greeting, setGreeting] = useState("");
6
    return (
7
        <>
8
            <Heading as="h4" size="md">
9
                {intl.formatMessage({ id: "serviceI18n.heading" })}
10
            </Heading>
11
            <HStack
12
                as="form"
13
                onSubmit={(e) => {
14
                    e.preventDefault();
15

16
                    const name = inputValue.trim();
17
                    if (name) {
18
                        setGreeting(greetingService.greet(name));
19
                    } else {
20
                        setGreeting("");
21
                    }
22
                }}
23
            >
24
                <Input
25
                    placeholder={intl.formatMessage({ id: "serviceI18n.placeholder" })}
26
                    value={inputValue}
27
                    onChange={(evt) => setInputValue(evt.target.value)}
28
                    size="md"
29
                />
30
                <Button type="submit" flexShrink={0}>
31
                    {intl.formatMessage({ id: "serviceI18n.showGreeting" })}
32
                </Button>
33
            </HStack>
34
            {greeting && (
35
                <Text>
36
                    {intl.formatMessage({ id: "serviceI18n.serviceResponse" })} {greeting}
37
                </Text>
38
            )}
39
        </>
40
    );
41
}

Demo App

The complete app i18n-howto can be found in the samples folder.

Changing the application’s locale

It is possible to change the application’s locale to a specific locale using the setLocale method on the ApplicationContext.

Example:

1
import { ApplicationContext } from "@open-pioneer/runtime";
2

3
const appCtx: ApplicationContext = ...; // injected
4
appCtx.setLocale("en-US");

Limitation: Currently, this requires a full restart of the application. Please create an issue or PR if you need support for changing the locale without restart.

For more information refer to the API of the core-packages runtime package.

HowToTranslateAnApp

How to translate an app

Preparing i18n support for our app

Using advanced features of FormatJS Intl

Interpolation

Plurals

Selection

Number Format

Date/Time Format and Relative Time Format

Formatting rich text

Using i18n in a service

Demo App

Changing the application’s locale

Further reading