Moving internationalized Connect apps to Forge

Internationalization for Forge is backwards compatible with internationalized Connect apps. If your Connect app was internationalized using localization keys and translation files, this feature will continue to work after adopting Forge. This means you can seamlessly transition your existing localization keys and translation files from Connect to Forge, maintaining the language support of your app.

When an internationalized Connect app adopts Forge:

• It continues to use the existing Connect modules, which are listed under connectModules in the Forge manifest.
• It provides the option to re-use the existing translation JSON files for Forge modules.

Using Connect modules in Forge

In your Forge manifest you'll find that the content for the former translations entry has been renamed to either jira:translations or confluence:translations and moved into the connectModules section.

Connect descriptor example

This "Hello World" Connect app uses the generalPages module for Jira. The name attribute uses the i18n object, which provides access to values from the three provided locales, en-US, de-DE, and zh-CN.

1
2
"modules": {
    "generalPages": [
        {
            "key": "hello-world",
            "location": "system.top.navigation.bar",
            "name": {
                "value": "Hello World",
                "i18n": "page.name"
            },
            "url": "/helloworld.html"
        }
    ]
},
"translations": {
    "paths": {
        "en-US": "/i18n/en-US.json",
        "de-DE": "/i18n/de-DE.json",
        "zh-CN": "/i18n/zh-CN.json"
    }
}

Resulting Forge manifest example

During the process of adopting Forge, the Connect descriptor is converted to a Forge manifest.

The generalPages Connect module and translations are moved to the connectModules section. Note that they have also been prefixed with jira:.

1
2
connectModules:
  jira:generalPages:
    - url: /helloworld.html
      key: hello-world
      location: system.top.navigation.bar
      name:
        value: Hello world
        i18n: page.name
  jira:translations:
    - paths:
        en-US: /locales/en_US.json
        en-ES: /locales/en-ES.json
        de-DE: /locales/de-DE.json
      key: connect-translations

This setup ensures backwards compatibility with the Connect modules that your app is using.

Re-using translation files

To re-use your translations files, you can make them available within Forge modules by declaring a new top level entry named translations in the Forge manifest.

Example

1
2
translations:
  resources:
    - key: en-US
      path: locales/en_US.json
    - key: de-DE
      path: locales/de-DE.json
    - key: es-ES
      path: locales/es-ES.json
  fallback:
    default: en-US

This will enable Forge modules to access the values for all language keys defined in those JSON files. For more details on configuring your Forge manifest to support internationalization, see Translations.

Re-using a language key

Let's say you want to add a Jira project page (jira:projectPage) to your app and since your app has adopted Forge, you want to use a Forge module. When you use the i18n attribute for translatable entries, such as titles or names, you can use any of the defined entries in your translations files.

Example

1
2
modules:
  jira:projectPage:
    - key: hello-world-project-page
      resource: main
      resolver:
        function: resolver
      render: native
      title:
        i18n: page.name

This project page uses the existing page.name entry from the former Connect app.

Translating the content of your app

Internationalization for Forge supports the translation of content defined in the manifest as well as in the frontend code of your app. For more information on adding translation resources to your frontend code, see useTranslation for UI Kit apps and i18n.createTranslationFunction for Custom UI apps.

The main difference between Connect and Forge is that Connect only supports flattened key formats, whereas Forge supports both flattened and nested key formats. This provides you with the option to switch from a flat key-value list to using nested keys when adding new language keys for Forge modules.

Example

The following is an example of a flat key format, which is supported by both Connect and Forge:

1
2
{
  "page.name": "Hello world",
  "page.description": "A greeting page"
}

The following is an example of a nested key format, which is only supported by Forge:

1
2
{
  "page": {
    "name": "Hello world",
    "description": "A greeting page"
  }
}