UI Kit components
Jira UI Kit components
UI Kit hooks
Forge bridge APIs
Jira bridge APIs
Upgrade UI Kit versions
Previous versions

i18n

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

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.

Function signature

1
2
const createTranslationFunction = (
  locale: ForgeSupportedLocaleCode | null = null
): Promise<TranslationFunction>

type TranslationFunction = (i18nKey: string, defaultValue?: string) => string;

Arguments

  • locale: The target locale code for the translation. This should be left unspecified or set to null so that the locale will default to the user's preferred locale, which is retrieved from view.getContext.

Returns

  • translation function: The translation function, known as the 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.
    • Arguments:
      • i18nKey: The key to be translated. The key should correspond to a string value in the translation files.
      • defaultValue: The default value to return if the translation key cannot be resolved.
    • Returns:
      • The translated string. This is the translation value that corresponds to the provided translation key. If the key is not found, the function returns the 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.

Example

1
2
import 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

getTranslations() retrieves the content of a translation file for a specified locale code.

Function signature

1
2
const 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;
}

Arguments

  • locale: The target locale code for the translation resource that will be fetched. This should be left unspecified or set to null so that the locale will default to the user's preferred locale, which is retrieved from view.getContext().
  • options:
    • fallback: Specifies whether the fallback configuration will be taken into account during the retrieval of the translation resource.

Returns

  • 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.

Example

1
2
import 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: