i18n API

This page explains createTranslationFunction and getTranslations which can be used to internationalize Forge functions. To add internationalization support for your app's frontend, see the useTranslation hook for UI Kit apps or the Forge bridge i18n function for Custom UI 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, which provides basic translation functionalities to internationalize your app.
• getTranslations, which allows you to integrate with third-party i18n frameworks, such as i18next. This allows you to access advanced translation features like interpolation, formatting, and plurals by preparing the translation resources for these i18n frameworks.

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
): Promise<TranslationFunction>

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

Arguments

• locale: The target locale code for the translation. Please refer to here for more information on how to access the locale information on the Forge function side.

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 api, { i18n } from "@forge/api";

const resolver = new Resolver();

resolver.define("getText", async (req) => {
  const t = await i18n.createTranslationFunction('en-US');
  return JSON.stringify({
    text: t("page.content"),
  });
});

export const handler = resolver.getDefinitions();

getTranslations

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

Function signature

1
2
const getTranslations = (
  locale: ForgeSupportedLocaleCode,
  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. Please refer to here for more information on how to access the locale information on the Forge function side.
• 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 api, { i18n } from "@forge/api";

const resolver = new Resolver();

resolver.define("getText", async (req) => {
  const { translations, locale } = await i18n.getTranslations("en-US");
  return JSON.stringify({
    translations,
    locale,
  });
});

export const handler = resolver.getDefinitions();

Accessing locale information in Forge functions

A user's locale information is not directly available to Forge functions. This is because:

• The Forge function runtime is shared across users.
• Not all Forge functions are user-specific, such as web triggers.

There are several ways for Forge functions to access a user's locale information. This includes:

• Passing the locale information from the frontend to the backend via the request payload.
• Using the product fetch API to retrieve the locale information from the product API.

  • For Confluence, you can use the getCurrentUser API to get the locale information for the current user.

    1
    2
    const getConfluenceLocale = async () => {
      const response = await api
        .asUser()
        .requestConfluence(route`/wiki/rest/api/user/current`, {
          headers: {
            Accept: "application/json",
          },
        });
      const confluence = await response.json();
    
      return confluence.locale;
    };
    

  • For Jira, you can use the getLocale API to get the locale information for the current user.

    1
    2
    const getJiraLocale = async () => {
      const response = await api
        .asUser()
        .requestJira(route`/rest/api/3/mypreferences/locale`, {
          headers: {
            Accept: "application/json",
          },
        });
      const jira = await response.json();
    
      return jira.locale;
    };