Localization

When building an application for use across many countries, it's essential to translate and localize your application for each user's location. Descope simplifies translating text within your flows and messaging templates by offering translation via connectors or manual overrides. When using a connector to translate a Descope Flow or messaging template, you can override the translation response from the third-party service to meet your needs.

This guide provides an overview of localization configuration. For detailed connector setup guides, see our Localization Connectors page.

You can also configure localization programmatically through the Descope Client SDKs by passing the locale parameter to the Descope component, giving you manual control over which language or locale is displayed for your flow.

Configuration Overview

To configure the localization of a Descope flow or messaging template, navigate to the Localization section within the Descope console. Once here, you can select the applicable flow or messaging template you want to localize from the dropdown, then click Configure Localization.

Once you have clicked Configure Localization, you will be prompted to select the connector, source language, and target languages.

When you select the dropdown for Connector, you can choose manual or use one of our Localization connectors.

After selecting Done, you will see a page similar to the one below. You can change the settings from the previous modal by clicking the settings icon at the top right. You can also import and export the translations via the arrows icon. You can also select the checkbox to View overrides only to show only the overridden items on the right-hand side for the selected language.

Manual Localization

After selecting the manual option for localization, you will see a screen like the example below. You can then manually override the translations per language.

Connector Based Localization

When configuring localization to utilize a localization connector, the localization will automatically be generated for the flow or messaging template based on the returned translation. Below you can see an example configuration and the generated translation.

Manually Overriding Connector Translations

When you configure localization with a connector, you can manually override the translation. When you override the translation, you will see the override highlighted like the below example.

Global Strings

Global Strings provide a centralized way to define reusable text values that can be referenced across flows, screens, and messaging templates. They are especially useful for maintaining consistent copy, supporting localization, and avoiding duplication of text throughout your authentication experiences.

You can define global strings in the dedicated Global Strings section of the Descope console. You define a unique key and associate it with one or more string values, each mapped to a specific language. At runtime, the system resolves references to these keys and renders the appropriate string based on the active language context.

You can reference global strings in your flows, screens, and messaging templates using the {{strings.<key>}} syntax. For example, if you have a global string key called greet with the value "Welcome!", you can reference it as {{strings.greet}}.

Localizing Errors

When it comes to translating errors, there are a few areas where you need to accomplish this.

Flow Components

Some Descope components have errors that are managed in the flow itself and can be localized within the localization section of the Descope console. Examples of these components would be the missing value messages or customized Validation Error Messages.

System Flow Errors

Descope system-level flow errors, such as OTP verification failures, must be translated using the Descope error transformer within the frontend SDK.

Below is an example of configuring the error transformer within the frontend SDK to localize system-level flow errors.

function errorTransformer(error) {
  const language = getClientLanguage(); // Function to get the client's language, e.g., 'en', 'es', 'de'

  const translationMap = {
    en: {
      OTPVerifyCodePhoneFailed: "Failed to verify OTP code",
    },
    es: {
      OTPVerifyCodePhoneFailed: "No se pudo verificar el código OTP",
    },
    de: {
      OTPVerifyCodePhoneFailed: "Der OTP-Code konnte nicht überprüft werden",
    },
    // Add more languages and translations as needed
  };

  const translations = translationMap[language] || translationMap['en']; // Default to 'en' if language not found

  return translations[error.type] || translations[error.text] || error.text;
}

function getClientLanguage() {
  // Logic to determine the client's language, e.g., from browser settings or user profile
  // For demonstration purposes, return 'en' (English) by default
  return navigator.language.split('-')[0] || 'en';
}

Custom Flow Errors

Descope allows you to generate customized error messages in conditions and actions. These custom errors must be translated using the Descope error transformer within the frontend SDK.

Below is an example of a configured flow error and how to configure the error transformer within the frontend SDK.

function errorTransformer(error) {
  const language = getClientLanguage(); // Function to get the client's language, e.g., 'en', 'es', 'de'

  const translationMap = {
    en: {
      "Trigger 404 failure": "I'm a pinecone",
    },
    es: {
      "Trigger 404 failure": "Soy una piña",
    },
    de: {
      "Trigger 404 failure": "Ich bin ein Pinienzapfen",
    },
    // Add more languages and translations as needed
  };

  const translations = translationMap[language] || translationMap['en']; // Default to 'en' if language not found

  return translations[error.type] || translations[error.text] || error.text;
}

function getClientLanguage() {
  // Logic to determine the client's language, e.g., from browser settings or user profile
  // For demonstration purposes, return 'en' (English) by default
  return navigator.language.split('-')[0] || 'en';
}

Language support

Descope includes built-in support for the following languages. If the language or locale you need isn't listed here, you can define one yourself as a custom language.

Dialect support

Descope supports additional localization dialects to enhance your end user's experience further.

Supported extended dialects include:

• zh-CN: Chinese (Simplified) as used in Mainland China
• zh-TW: Chinese (Traditional) as used in Taiwan
• en-GB: English as used in the United Kingdom
• it-IT: Italian as used in Italy
• it-CH: Italian as used in Switzerland
• fr-CA: French as used in Canada
• fr-FR: French as used in France
• pt-BR: Portuguese as used in Brazil
• pt-PT: Portuguese as used in Portugal
• es-MX: Spanish as used in Mexico
• es-US: Spanish as used in the United States
• ms-Arab: Malay in Arabic script (Jawi)
• pa-Arab: Punjabi in Arabic script (Shahmukhi)
• fa-AF: Dari as used in Afghanistan

Dialects with connectors

The AWS Translate and Google Cloud Translate connectors don't support all of the Descope-supported dialects.

AWS Translate does not support en-GB. Google Cloud Translate does not support en-GB, fr-CA, or es-MX.

Custom Languages

Descope ships with a long list of built-in languages. However, if the language or locale you need isn't in the built-in language list, you can define your own entry with a display name and a language code of your choosing, then localize your flows, messaging templates, and global strings with your language.

Custom languages are scoped to a project. Once you create one, it's available as a target language for other localization items in the same project.

Adding a Custom Language

Custom languages can only be added as target languages. Descope does not support custom source languages, so the Source Language input always lists built-in languages only.

The dialog accepts the following values:

Click Add Language to save. The new language appears immediately in the Custom group of the Target Languages dropdown, where you can select it and begin entering translations.