Ping SDKs

Localizing the user interface

Applies to:

  • DaVinci client for Android

  • DaVinci client for iOS

  • DaVinci client for JavaScript

You can leverage the languages feature in PingOne to localize your client applications for different audiences.

The DaVinci clients automatically send the preferred languages configured in the browser or mobile device to PingOne so that it can return the appropriate language.

Console output from an iOS client showing Accept-Language header
[Ping SDK 1.1.0] ⬆
Request URL: https://auth.pingone.com/c2a6...1602/as/authorize?response_mode=pi.flow&client_id=85ff...6791&response_type=code&scope=openid&redirect_uri=http://localhost:5829&code_challenge=m8BD...rhPM&code_challenge_method=S256
Request Method: GET
Request Headers: [
    "x-requested-platform": "ios",
    "Content-Type": "application/json",
    "x-requested-with": "ping-sdk",
    "Accept-Language": "en-GB, en;q=0.9"
]
Request Timeout: 15.0

You can also override the configured settings directly in your code if required.

Before you begin

You must configure PingOne to support multiple languages that your client apps can use:

  1. In PingOne, enable the built-in languages you want to support.

    Learn more in Enabling or disabling a language.

    You can also add your own languages and regions.

    Learn more in Adding a language.

  2. Ensure your language has the required localized strings for your clients to use.

    Learn more in Modifying translatable keys.

    You can also add your own keys to a language for use in your client applications.

    Learn more in Adding a custom key for DaVinci.

  3. Add your localized strings to your chosen implementation:

    PingOne forms

    Update the fields in your PingOne forms to use translatable keys.

    Adding localized strings to a PingOne form.
    Figure 1. Adding localized strings to a PingOne form

    Learn more in Using translatable keys.

    Custom HTTP Connector

    Update the Output Fields in your custom HTML to use your localized strings.

    Adding localized strings to a custom HTTP connector

    Adding localized strings to a custom HTTP connector.

    Learn more in HTTP Connector.

Configuring a DaVinci client to send the language header

The DaVinci clients automatically send the Accept-Language header when making requests to the PingOne server. This header includes each of the languages configured on the client device or in the browser, and maintains the order of preference.

The DaVinci client for Android and iOS also add generic versions of sub-dialects configured on the device, to make it more likely that PingOne can fall back to a similar language if the specific sub-dialect is unavailable.

For example, configuring English (British) (en-GB) as a preferred languages causes the DaVinci client to also send English (en) as a fallback option:

"Accept-Language": "en-GB, en;q=0.9"

Overriding the automatically-added languages

You can override the default behavior of automatically sending configured languages.

  • DaVinci client for Android

  • DaVinci client for iOS

  • DaVinci client for JavaScript

To provide your own values for the Accept-Language header, use the CustomHeader module.

Add the module to your DaVinci configuration as follows:

Using the CustomHeader module to override default language behavior
import com.pingidentity.davinci.DaVinci
import com.pingidentity.davinci.module.Oidc
import com.pingidentity.davinci.module.CustomHeader

val daVinci = DaVinci {
    module(Oidc) {
        clientId = "6c7eb89a-66e9-ab12-cd34-eeaf795650b2"
        discoveryEndpoint = "https://auth.pingone.com/3072206d-c6ce-ch15-m0nd-f87e972c7cc3/as/.well-known/openid-configuration"
        scopes = mutableSetOf("openid", "profile", "email", "address", "revoke")
        redirectUri = "org.forgerock.demo://oauth2redirect"
        additionalParameters = mapOf("customKey" to "customValue")
    }

    // Add French as the preferred language, before default options
    module(CustomHeader, priority = 5, mode = OverrideMode.APPEND) {
        header(name = "Accept-Language", value = "fr")
    }
}
priority

Default behavior of the DaVinci client is provided by a number of built-in modules. These modules all run with a priority value of 10.

  • To run your module before the default modules ensure your module has a priority value less than the default of 10.

  • To run your module after the default modules, set the prioriy value to greater than 10.

mode

You can choose how the CustomHeader module applies the modification by using the mode parameter:

OverrideMode.APPEND

The DaVinci client combines any additional parameters you provide with any parameters the default behavior adds.

The order is determined by the priority order of the modules.

OverrideMode.OVERRIDE

Any additional parameters you provide replace any parameters the default behavior would have added.

To provide your own values for the Accept-Language header, use the CustomHeader module.

Add the module to your DaVinci configuration as follows:

Using the CustomHeader module to override default language behavior
import PingDavinci

public let davinci = DaVinci.createDaVinci { config in
    let currentConfig = ConfigurationManager.shared.currentConfigurationViewModel
    config.module(OidcModule.config) { oidcValue in
        oidcValue.clientId = "6c7eb89a-66e9-ab12-cd34-eeaf795650b2"
        oidcValue.scopes = ["openid", "profile", "email", "address", "revoke"]
        oidcValue.redirectUri = "org.forgerock.demo://oauth2redirect"
        oidcValue.discoveryEndpoint = "https://auth.pingone.com/3072206d-c6ce-ch15-m0nd-f87e972c7cc3/as/.well-known/openid-configuration"
    }

    // Add French as the preferred language, before default options
    config.module(CustomHeader.config, priority: 5, mode: .append) { customHeaderValue in
        customHeaderValue.header(name: "Accept-Language", value: "fr")
    }
}
priority

Default behavior of the DaVinci client is provided by a number of built-in modules. These modules all run with a priority value of 10.

  • To run your module before the default modules ensure your module has a priority value less than the default of 10.

  • To run your module after the default modules, set the prioriy value to greater than 10.

mode

You can choose how the CustomHeader module applies the modification by using the mode parameter:

.append

The DaVinci client combines any additional parameters you provide with any parameters the default behavior adds.

The order is determined by the priority order of the modules.

.override

Any additional parameters you provide replace any parameters the default behavior would have added.

To override the default browser behavior and provide your own values for the Accept-Language header, use the RequestMiddleware type.

Call your request middleware when creating the DaVinci client as follows:

Using the CustomHeader module to override default language behavior
import { davinci } from '@forgerock/davinci';
import type { RequestMiddleware } from '@forgerock/davinci-client/types';

const requestMiddleware: RequestMiddleware[] = [
  (fetchArgs, action, next) => {
    fetchArgs.headers?.set('Accept-Language', 'fr-FR, fr;q=0.9');
    next();
  },
];

const davinciClient = await davinci({
  config: {
    clientId: '6c7eb89a-66e9-ab12-cd34-eeaf795650b2',
    serverConfig: {
      wellknown: 'https://auth.pingone.com/3072206d-c6ce-ch15-m0nd-f87e972c7cc3/as/.well-known/openid-configuration',
      timeout: 3000,
    },
    scope: 'openid profile email address revoke',
    responseType: 'code',
  },
  requestMiddleware
});