Skip to main content

Translations and Internationalization (i18n)

Translations and internationalization​

Your customers may require non-English language support. Internationalization (i18n) enables you to localize the embedded marketplace interface into multiple languages.

Review the marketplace's translations package. This repository contains all translatable phrases in the marketplace, along with their English source text. There are three categories of translatable phrases:

  • SimplePhrase: Direct string-to-string translations. Example: input.integrationVersionLabel "Integration Version" translates to French "Version d'intégration".
  • ComplexPhrase: Template strings that incorporate variables representing customer names, integration names, counts, etc. Example: integrations.id__banner.customerActivateText with value "Please contact %{organization} to activate this integration." This template injects your organization's name into the string.
  • Dynamic Phrases: Translations of your custom content (integration names, configuration variable keys, etc.), detailed below.

An example of i18n in action is available in our example embedded app on GitHub.

Adding an i18n dictionary for a user​

To apply an i18n dictionary to a user, include a translation property in your prismatic.init invocation. You can also add phrases to prismatic.showMarketplace or similar functions to apply translations to specific iframes. Include any phrases that require translation:

Translating phrases
prismatic.init({
  translation: {
    phrases: {
      // Static Translations:
      "integration-marketplace__filterBar.allButton": "Alle, bitte!",
      "integration-marketplace__filterBar.activateButton": "Solo activado",
      "detail.categoryLabel": "カテゴリー",
      "detail.descriptionLabel": "विवरण",
      "detail.overviewLabel": "概述",

      // Complex translation with variables:
      "activateIntegrationDialog.banner.text--isNotConfigurable": {
        _: "Veuillez contacter %{organization} pour activer cette intégration",
      },
    },
  },
});

After implementing changes, reload the marketplace to view the new translations.

Use Intellisense

The Marketplace NPM package includes inline documentation showing current English values for translatable phrases. Enable intellisense in your code editor and hover over the target phrase to view its English source text.

i18n debug mode​

To identify which phrase corresponds to which UI element in Prismatic, enable debug mode by adding debugMode: true to the translation property of prismatic.init:

Enable debug mode for translations
prismatic.init({
  translation: {
    debugMode: true,
  },
});

This will display phrase keys and their current values for all UI elements in the embedded marketplace:

Namespaced phrases​

Certain phrases are shared across multiple pages in the embedded marketplace. A comprehensive list of these common phrases is available on GitHub.

For example, common.loading translates to "Loading" in English across multiple screens. Setting common.loading once will affect all instances of this phrase.

To customize common phrases on a per-page basis, you can namespace phrases. For instance, to translate common.loading differently only on the alert monitors page, prefix the phrase key with a PhraseNamespace using the format NAMESPACE__PHRASE-KEY (see translations):

Namespacing phrases
prismatic.init({
  translation: {
    phrases: {
      "integrations.id.alert-monitors__common.loading": "Sit tight a sec...",
    },
  },
});

Dynamic phrases​

As you develop integrations, you create organization-specific phrases. These custom phrases include:

  • Integration names
  • Config variable names
  • Config wizard page titles
  • Config wizard page descriptions
  • Config wizard helper text
  • Flow names (visible to customers in execution results)
  • Step names (visible to customers in execution results)

You can translate these phrases by adding a dynamicPhrase property to the phrases object. For example, to translate an integration named "Sync customer data with Salesforce" to French, add a dynamicPhrase to your prismatic.init invocation:

prismatic.init({
  translation: {
    phrases: {
      dynamicPhrase: {
        "Sync customer data with Salesforce":
          "Synchronisez les données clients avec Salesforce",
      },
    },
  },
});

You can override any other dynamic phrases using the same method.

prismatic.init({
  translation: {
    phrases: {
      dynamicPhrase: {
        "Microsoft Teams": "Microsoft Squadre", // Integration name
        "Notify a Teams channel of new leads":
          "Notifica un canale di Teams di nuovi lead", // Integration description
        "Teams Configuration": "Configurazione di Teams", // Config wizard page title
        "Enter your Teams authentication info": "", // Config wizard page subtitle
        "Teams Authentication": "Autenticazione di Teams", // Config variable
        "<h1>Teams OAuth</h1>": "<h1>OAuth di Teams</h1>", // HTML helper text in the config wizard
      },
    },
  },
});
Dynamic phrases must match exactly

Dynamic phrases must exactly match the phrases used in your integration. If your config variable includes capitalization or punctuation, you must include these in the dynamic phrase. Partial matches will not translate (e.g., translating {"Customer": "Cliente"} will not translate "Customer Name" to "Cliente Name").

Note the <h1> tag in the last example. When providing custom HTML helper text in your configuration wizard, you must translate the complete HTML string.

Listing all dynamic phrases​

To view all translatable dynamic phrases from your account, use the prism CLI:

List all dynamic phrases for all integrations in marketplace
prism translations:list

This command generates a translations_output.json file in your current directory containing all dynamic phrases for your account or a specific integration. Use this file as a reference when populating your dynamicPhrase object.