Plugin example of using translations

This advanced TypeScript plugin example demonstrates the use of translations. A record parameter provides a translation table for easy editing. The plugin automatically detects the current language and displays the appropriate text. It includes default texts in both manifest.json and the code, allowing updates to the plugin without requiring simultaneous changes to the plugin configuration.

myplugin.ts

Plugin that display a title and a description in a div.

import { useLocalization } from './locale';
import { MypluginContext } from './config';

export default async (context: MypluginContext) => {
    context.componentLoader.registerBlockComponent({
        location: 'start-bottom',
        loadContent: async ctx => {
            const { shadow } = ctx;

            const css = new CSSStyleSheet();
            await css.replace(`
                div {
                    font-size: 1rem;
                }
            `);
            shadow.adoptedStyleSheets.push(css);

            const { getText } = useLocalization(context);

            const container = document.createElement('div');
            container.innerHTML = `
                <h1>${getText('title')}</h1>
                <p>${getText('description')}</p>
            `;
            shadow.appendChild(container);
        },
    });
};

manifest.json

{
    "version": "1.0.0",
    "description": "Adds reward plugin",
    "esm": true,
    "parameters": [
        {
            "name": "translations",
            "friendlyName": "Translations",
            "description": "Json with translations",
            "required": false,
            "schema": {
                "type": "record",
                "keys": {
                    "type": "string"
                },
                "values": {
                    "type": "object",
                    "properties": {
                        "title": {
                            "type": "string"
                        },
                        "description": {
                            "type": "string"
                        }
                    }
                }
            },
            "defaultValue": {
                "en": {
                    "title": "Points & Rewards",
                    "description": "Gather points and earn rewards"
                },
                "sv": {
                    "title": "Poäng & Erbjudanden",
                    "description": "Samla poäng of få erbjudanden"
                }
            }
        }
    ]
}

config/index.ts

import { PluginContext } from '@futureordering/fo-web-plugin-types';
import { LocalizedStringsValues } from '../locale';

export type MypluginContext = PluginContext & {
    config: {
        translations?: Partial<Record<string, Partial<LocalizedStringsValues>>>;
    };
};

locale/defaults/en.ts

import { LocalizedStringsValues } from '..';

export const en: LocalizedStringsValues = {
    title: 'Points & Rewards',
    description: 'Gather points and redeem rewards',
};

locale/defaults/sv.ts

import { LocalizedStringsValues } from '..';

export const sv: LocalizedStringsValues = {
    title: 'Poäng & Erbjudanden',
    description: 'Samla poäng och lös in erbjudanden',
};

locale/index.ts

import { MypluginContext } from '../config';
import { en } from './defaults/en';
import { sv } from './defaults/sv';

export type LocalizedStrings = {
    title: {
        value: string;
    };
    description: {
        value: string;
    };
};

export const defaultLocales = {
    en,
    sv,
} as const satisfies Record<string, LocalizedStringsValues>;

export type LocalizedStringsValues = Record<keyof LocalizedStrings, string>;

export function useLocalization(context: MypluginContext) {
    const getText = <T extends keyof LocalizedStrings>(key: T) => {
        const languageCode = context.environment.getLanguageCode();

        const isDefaultSupportedLang = (
            languageCode: string
        ): languageCode is keyof typeof defaultLocales => languageCode in defaultLocales;

        const fallbackLanguageCode =
            languageCode && isDefaultSupportedLang(languageCode) ? languageCode : 'en';

        const configValue = languageCode
            ? context.config.translations?.[languageCode]?.[key]
            : undefined;
        const fallbackValue = defaultLocales[fallbackLanguageCode][key];

        return configValue ?? fallbackValue;
    };

    return { getText };
}