UI localization and i18n

Reactodia has a built-in support for UI text strings localization. Each UI component in the library that displays text labels or descriptions resolves them from translation bundles via Translation interface.

Translation bundle

Localized texts are organized in a form of plain JSON objects called TranslationBundle. The bundle have the following structure:

{
    "$schema": "../i18n.schema.json",
    "component_name": {
        "some_action.label": "Some Action",
        "some_action.title": "Performs some action",
        "truncate_data.command": "Truncate Data",
        "graph_edge.label": "{{start}} → {{end}}",
        ...
    },
    ...
}

Built-in translation bundles references the JSON schema to validate mistyped or unknown translation keys. This schema is available as @reactodia/workspace/i18n/i18n.schema.json and can be used with external JSON validation tool (e.g. ajv-cli) to check the translations.

To provide customized translation, additional bundles can be passed to Workspace component with translations property:

function TranslationOverride() {
    return (
        <Reactodia.Workspace
            translations={[
                {
                    'default_workspace': {
                        'search_section_entity_types.label': 'Class Tree',
                        'search_section_entity_types.title': 'Class tree hierarchy',
                    }
                }
            ]}>
            <Reactodia.DefaultWorkspace />
        </Reactodia.Workspace>
    );
}

Additional built-in or custom translation can be used the same way by loading the JSON bundle externally and pass them with translations property in th order of the one with the high priority to low priority. Default en translation (@reactodia/workspace/i18n/translations/en.reactodia-translation.json) is always enabled as a fallback unless useDefaultTranslation={false} is specified:

import enUkTranslation from './en-uk.reactodia-translation.json';
import deTranslation from './de.reactodia-translation.json';

function MultipleTranslations() {
    return (
        <Reactodia.Workspace
            translations={[deTranslation, enUkTranslation]}
            useDefaultTranslation={false}>
            <Reactodia.DefaultWorkspace />
        </Reactodia.Workspace>
    );
}

Using translation in the custom components

The localization mechanism can be used for a custom component nested inside the Workspace by getting a Translation instance which can be used to format localizable strings.

useTranslation() hook can be used to acquire the Translation object; alternatively it is available as part of the WorkspaceContext via WorkspaceContext.translation property.

In the following example, additional custom translation keys are added to the workspace to provide localizable component labels:

Result

Loading...

Live Editor

function MyComponent() {
    const t = Reactodia.useTranslation();
    return (
        <Reactodia.ToolbarAction
            title={t.text('my_component.do_action.title')}
            onSelect={() => alert('Done')}>
            {t.text('my_component.do_action.label')}
        </Reactodia.ToolbarAction>
    );
}

function CustomTranslationKeys() {
    const {defaultLayout} = Reactodia.useWorker(Layouts);
    return (
        <div className='reactodia-live-editor'>
            <Reactodia.Workspace defaultLayout={defaultLayout}
                translations={[
                    {
                        'my_component': {
                            'do_action.label': 'Do the impossible!',
                            'do_action.title': 'Perform the impossible action',
                        }
                    }
                ]}>
                <Reactodia.DefaultWorkspace
                    actions={<MyComponent />}
                />
            </Reactodia.Workspace>
        </div>
    );
}

render(<CustomTranslationKeys />);