Localize a plugin (Public Beta)

Use this guide to localize your plugins so they display in the same language as the native Flex UI when a user changes their language setting.

To render plugin text in a different language, follow these steps:

1. Add a file with localized static strings for each language that's available.
2. In the same file, add localized dynamic strings.
3. In your plugin file, add code to read Flex's current locale so the plugin can determine which language to use.
4. Update your plugin components to use the localized strings.

This guide assumes your plugin uses a file structure similar to this:

• PluginName
  • src
    • components: directory that contains your plugin components.
    • locales: directory that contains your localization files.
      • es-MX.js: file that contains the localized strings for Español (México).
      • en-US.js: file that contains the localized strings for English (US).
      • pt-BR.js: file that contains the localized strings for Português (Brasil).
    • index.ts
    • PluginName.ts: file that contains the plugin code, including the code to read Flex's locale setting.

1. In your locales directory, add a file for each supported language.
2. In each file, define your custom strings and their translations.

The code samples below show an example string for Español (México) and for English (US), respectively.

To localize dynamic strings, such as agent status, add strings and their translations to the localization file for each language using the following format. You can localize both default and custom strings.

Your plugin can read Flex's current locale setting from the manager object at manager.localization.localeTag. The localeTag property defines the Internet Engineering Task Force (IETF) language tag of the current UI locale. For example, en-US.

To read Flex's current locale:

1. In your plugin file, add code to read the locale and apply the defined strings based on the localeTag value.
   

1
// Read Flex's locale setting
2
const localeTag = manager.localization.localeTag; // e.g. "en-US"
3
// Conditionally apply the relevant strings
4
switch (localeTag) {
5
case "en-US":
6
manager.strings = {...usEnglishStrings, ...manager.strings }
7
break;
8
case "es-MX":
9
manager.strings = {...mexicanSpanishStrings, ...manager.strings }
10
break;
11
}

2. (Optional) If you want to make other locale-related customizations, see the Flex UI API reference for more information about these available properties:
   • availableLocales: The list of locales the user sees when setting their language. Currently, this list is read-only.
   • setLocalePreference: A method to save the user's locale preference without using the native language selector. You can use this for implementing a custom locale selection widget.

In the definition for each component, add the custom string label you defined to localize that component. For example, step 1 shows how to define a string for WelcomeButton, and the code sample below shows how to add that string to the WelcomeButton component.

1
// Use your localized strings in a component
2
const WelcomeButton = ({strings}) => (<Button>{strings.WelcomeButton}</Button>));
3
...
4
<WelcomeButton strings={customStrings}/>

This lets Flex show the locale-specific string based on the current UI locale.