Translations

You can internationalize your Forge app by defining translation resources in your app’s manifest.yml file. This allows your app to support multiple languages and adapt based on a user’s language and locale.

Internationalization can be utilized by UI Kit apps (including apps using the Frame component) as well as Custom UI apps. The internationalization capability in Forge supports both:

• Elements of the UI defined in the app manifest that are displayed in Atlassian products. For example, the title of your app.

• Elements of the UI defined in the frontend code of your Forge app. For more information on adding translation resources to your frontend code, see useTranslation and i18n.

The translations configuration specified in this section is shared across the modules defined in the manifest.yml file.

Manifest structure

1
2
modules {}
└─ confluence:globalPage []
   ├─ key: my-page
   ├─ resource: main
   ├─ render: native
   ├─ route: my-page
   └─ title: (string | i18n)
   │  └─ i18n: page.title (string)
translations: {}
└─ resources: {}
   ├─ key: en-US (string)
   └─ path: locales/en-US.json (string)
└─ fallback: {}
   ├─ default: en-US (string)
   └─ zh-CN: []
   │  ├─ zh-TW
   │  └─ ja-JP

Properties

Translation resources

Translation resources define the locales and translated content supported by your Forge app. Each resource entry includes the locale code and the file path for the respective locale's translation file.

Translation fallback

Translation fallback is essential to guarantee that users can still access meaningful content when translations for their locale are unavailable. It ensures a consistent and user-friendly experience, stepping in when the desired locale is not supported, translations are incomplete, or only partial translations are available.

Example

manifest.yml

1
2
modules:
  confluence:globalPage:
    - key: my-page
      resource: main
      render: native
      route: my-page
      title:
        i18n: page.title
    - key: my-app
      resource: main
      render: native
      route: my-app
      title:
        i18n: appName
    - key: my-header
      resource: main
      render: native
      route: my-header
      title:
        i18n: header
translations:
  resources:
    - key: en-US
      path: locales/en-US.json
    - key: zh-CN
      path: src/frontend/locales/zh-CN.json
    - key: zh-TW
      path: locales/zh-TW.json
    - key: de-DE
      path: locales/de-DE.json
  fallback:
    default: en-US
    zh-TW:
      - zh-CN
    ja-JP:
      - de-DE
      - zh-CN

Translation files

1
2
// locales/en-US.json
{
  "appName": "My cool app",
  "header": "My header",
  "page": {
    "title": "My page title"
  },
  "custom.content": "used within the app not manifest.yml"
}

1
2
// src/frontend/locales/zh-CN.json
{
  "page.title": "我的页面标题 (zh-CN)",
  "page": {
    "title": "我的页面标题 (not used)"
  },
  "header": "我的标题 (zh-CN)"
}

1
2
// locales/zh-TW.json
{
  "page": {
    "title": "我的頁面標題 (zh-TW)"
  }
}

1
2
// locales/de-DE.json
{
  "header": "Meine Kopfzeile (de-DE)"
}

Explanation

Let’s examine the manifest.yml file and the associated translation files to understand how this setup works.

Translatable module properties

In the manifest.yml file some module properties, such as the title of the confluence:globalPage module, support translations.

1
2
modules:
  confluence:globalPage:
    - key: my-page
      resource: main
      render: native
      route: my-page
      title:
        i18n: page.title
    - key: my-app
      resource: main
      render: native
      route: my-app
      title:
        i18n: appName
    - key: my-header
      resource: main
      render: native
      route: my-header
      title:
        i18n: header

To enable translation support, change the attribute type from a string to an i18n object.

For example, before adding translation support, this looks like:

1
2
title: My page title

After adding translation support, this looks like:

1
2
title:
  i18n: page.title

When you change the module property from a string to an i18n object, Forge can use the translation key page.title to retrieve the value for the title property from the translation files.

Path to the translation files

The manifest.yml section outlining the locale code and its corresponding translation file path is found under translations.resources.

Each translation resource has a key and path. The key is one of the supported locale codes. The path is the relative path from the top-level directory of your app to the translation file. It is good practice to name the file in the format <locale-code>.json, where the locale code is one of the supported locales.

1
2
translations:
  resources:
    - key: en-US
      path: locales/en-US.json
    - key: zh-CN
      path: src/frontend/locales/zh-CN.json
    - key: zh-TW
      path: locales/zh-TW.json
    - key: de-DE
      path: locales/de-DE.json

These files can be located within the UI Kit frontend source code (for example, src/frontend/locales/zh-CN.json), in the project root directory (for example, locales/en-US.json), or in other specified locations within the project. If a translation file needs to be shared across multiple frontend code bundles, it is best to store the translation files in the project root directory.

Fallback configuration

The manifest.yml file also specifies the fallback configurations, including the default and target fallback locales. If the target fallback rules fail to resolve the translation, the content from the default fallback will be used.

1
2
  fallback:
    default: en-US
    zh-TW:
      - zh-CN
    ja-JP:
      - de-DE
      - zh-CN

You need to configure translation files for the fallback locales in the translation.resources section of the manifest. In the example above, these locales are en-US, de-DE, and zh-CN. If file paths for any of these locales are not configured, a validation error will be thrown when you attempt to deploy the app.

The translation file for the default fallback is required to include translations for all exposed translation keys in the app manifest. If any of these i18n keys cannot be resolved in the default fallback translation file, a validation error will be thrown. The app cannot be deployed until this has been resolved.

The table below explains the fallback logic for this example:

1
2
// locales/en-US.json
{
  "appName": "My cool app",
  "header": "My header",
  "page": {
    "title": "My page title"
  },
  "custom.content": "used within the app not manifest.yml"
}

1
2
// src/frontend/locales/zh-CN.json
{
  "page.title": "我的页面标题 (zh-CN)",
  "page": {
    "title": "我的页面标题 (not used)"
  },
  "header": "我的标题 (zh-CN)"
}

1
2
// locales/zh-TW.json
{
  "page": {
    "title": "我的頁面標題 (zh-TW)"
  }
}

1
2
// locales/de-DE.json
{
  "header": "Meine Kopfzeile (de-DE)"
}

Translation files

The translation files provide key-value pairs to be used by Forge to execute the translation. Each key represents a unique identifier, such as header or page.title, while the corresponding value is the translation to be displayed, such as "My header" or "My page title".

1
2
// locales/en-US.json
{
  "appName": "My cool app",
  "header": "My header",
  "page": {
    "title": "My page title"
  },
  "custom.content": "used within the app not manifest.yml"
}

The content of the translation files supports both nested and flattened key formats.

For example, a nested key format looks like:

1
2
{
  "page": {
    "title": "My page title"
  }
}

A flattened key format looks like:

1
2
{
  "page.title": "My page title"
}

The support for both formats ensures portability with Connect apps. When both methods are used to define a key-value pair, the flattened key is prioritized over a nested key lookup.

For example, in the src/frontend/locales/zh-CN.json file mentioned earlier, when resolving the translation for the key page.title, the content (我的页面标题 (zh-CN)) associated with the flattened key page.title will be used, instead of the content (我的页面标题 (not used)) linked to the corresponding nested key.

We recommend using the nested key format as it typically results in a more compact file size and improved maintainability.