Internationalization (i18n) for Forge apps is now available through Forge's Early Access Program (EAP). For details on how to sign up for the EAP, see the changelog announcement.
EAPs are offered to selected users for testing and feedback purposes. APIs and features under EAP are unsupported and subject to change without notice. APIs and features under EAP are not recommended for use in production environments.
For more details, see Forge EAP, Preview, and GA.
This page explains the createTranslationFunction and getTranslations functions which can be used to internationalize Forge apps. While these functions can be used for both Custom UI and UI Kit apps, we recommend using the useTranslation UI Kit hook to internationalize UI Kit apps.
The i18n
APIs allow you to access the translation resources configured in Translations so that your app can adapt based on a user’s language and locale. There
are two functions available:
createTranslationFunction()
allows you to generate a translation function, referred to as the t
function, bound to a specified locale code. This function performs translations by replacing
the requested translation key with its respective localized string based on the translation files specified
in the app manifest.
1 2const createTranslationFunction = ( locale: ForgeSupportedLocaleCode | null = null ): Promise<TranslationFunction> type TranslationFunction = (i18nKey: string, defaultValue?: string) => string;
null
so that the locale will default to the user's preferred locale, which is retrieved from
view.getContext.t
function, which
performs translations by replacing the translation key with the translation value. It uses the
assigned locale code and fallback settings, if required, to determine the appropriate translation.
defaultValue
if provided.
If the key is not found and no defaultValue
is provided, it returns the translation key itself
to help identify which translations are missing.1 2import React, { useState, useEffect } from "react"; import { i18n } from "@forge/bridge"; const App = () => { const [{ t }, setT] = React.useState({ t: null }); useEffect(() => { const loadTranslator = async () => { const t = await i18n.createTranslationFunction(); setT({ t }); }; loadTranslator(); }, [setT]); if (!t) { return <div>loading...</div>; } return ( <div>{t('page.content')}</div> ); };
getTranslations()
retrieves the content of a translation file for a specified locale
code.
1 2const getTranslations = ( locale: ForgeSupportedLocaleCode | null = null, options: GetTranslationsOptions = { fallback: true } ): Promise<GetTranslationsResult> interface GetTranslationsOptions { fallback: boolean; } interface GetTranslationsResult { locale: ForgeSupportedLocaleCode; translations: TranslationResourceContent | null; } interface TranslationResourceContent { [key: string]: string | TranslationResourceContent; }
null
so that the locale will default to the user's preferred locale,
which is retrieved from view.getContext().locale: The locale code of the translation resource returned within the payload. If the
fallback
option is enabled and the translation resource for the requested locale is unavailable,
the returned locale might differ from the requested one as the function retrieves the translation
resource from the corresponding fallback locale instead.
translations: The parsed content of the translation file for the specified locale. If the
translation file and fallback can't be found for the given locale, the function returns null
. The
getTranslations()
function retrieves the complete content of the specified translation file. In
this process, the fallback
setting is not implemented at the specific translation key level.
Therefore, if the intended translation key is absent from the designated translation file, you might
need to obtain the required content for that key by requesting an alternative translation file.
1 2import React, { useState, useEffect } from "react"; import { i18n } from "@forge/bridge"; const App = () => { const [translations, setTranslations] = React.useState(null); const [locale, setLocale] = React.useState(null); useEffect(() => { const loadTranslations = async () => { const { translations, locale } = await i18n.getTranslations(); if (translations) { setTranslations(translations); setLocale(locale); } }; loadTranslations(); }, [setTranslations, setLocale]); if (!translations) { return <div>loading...</div>; } return ( <> <div>locale: {locale}</div> <div>translations: {JSON.stringify(translations)}</div> </> ); };
Rate this page: