PingOne Platform APIs

Language Translations

The translations endpoint supplies operations to view the custom string translations for a specified language, and to update localized strings for UI elements in the specified language.

After you change a language locale or translation configuration, it might take up to 30 seconds for DaVinci to reflect the update.

The response for a GET request returns the embedded resources that supply UI strings in English, and the associated localized string content in the specified language. Here’s a sample of a localized string (in French) for the Cancel button in the flow-ui module used in a UI page:

    "_embedded": {
        "translations": [
            {
                "id": "3e90224d-9036-4d78-badb-65e98f4fc944",
                "key": "flow-ui.button.cancel",
                "shortKey": "button.cancel",
                "referenceText": "Cancel",
                "translatedText": "Annuler"
            },

PingOne support UI string translations for the following languages:

Locale Language

de

German

en

English

es

Spanish

fr

French

fr-CA

French (Canadian)

it

Italian

ja

Japanese

ko

Korean

nl

Dutch

pt

Portuguese

ru

Russian

th

Thai

tr

Turkish

zh

Chinese

cs

Czech

Languages translation request data model

For PUT requests, the following properties are required in the request body.

Property Type Required Mutable Description

key

String

Required

Mutable

A string that specifies the page and name of the interface element to be localized (for example, flow-ui.button.cancel).

translatedText

String

Required

Mutable

A string that specifies the translated string text associated with the interface element.

PUT operations do not return data in the response. A successful update request returns a 200 OK status.

Languages translation response data model

For GET requests, the data model returns the following information about the specified language’s localized strings.

Property Type Description

translations.id

String

The translation ID for a specific string.

translations.key

String

The page and name of the interface element to be localized (for example, flow-ui.button.cancel).

translations.shortKey

String

The interace element only (for example, button.cancel).

translations.referenceText

String

The English string text associated with the interface element.

translations.translatedText

String

The translated string text associated with the interface element.

Response codes

Code Message

200

Successful operation.

400

The request could not be completed.

401

You do not have access to this resource.

403

You do not have permissions or are not licensed to make this request.

404

The requested resource was not found.

Language translations errors

In addition to the general error codes, language translation operations can return the following errors:

HTTP status Top‑level code Detail code When it happens and what the response contains

400

INVALID_REQUEST

None

Message: The service-specific message describing the violated rule.

When and details

When: A POST /translations/en request supplies an empty translatedText, a translatedText for a non-English language, a key not prefixed with forms., a key longer than 500 characters, a translatedText with invalid ICU plural syntax, a key that already exists or matches a provided translation, or a request that would exceed the maximum number of custom translations per module (500 by default)

Details: None. Representative messages: Translation must not be empty., You cannot create custom translations for Non-English language., Custom translations are only supported for the 'forms' module., The translation key cannot exceed 500 characters.:

Invalid ICU plural syntax. Keep any trailing text outside the plural block. Example: \{count, plural, =1 \{character} other \{characters}} required

The maximum number of custom translations per module is limited to 500, The translation key already exists. Please update the existing translation key., The translation key already exists in the provided translations. Please update the existing translation key.

400

INVALID_REQUEST

None

Message: The service-specific message describing the violated rule.

When and details

When: A PUT /translations/en request’s bundle is empty, exceeds 1000 entries, supplies a key longer than 500 characters, supplies a translation longer than 1024 characters, supplies a key with characters outside letters, numbers, dashes, underscores, and dots, supplies an empty key, or creates a new key with an empty translation

Details: None. Representative messages: There is no translation., The number of translations for each upload cannot exceed 1000., Key must not be empty., The translation key can only contain letters, numbers, dashes, underscores, or dots., The translation key cannot exceed 500 characters., The translation cannot exceed 1024 characters., Translation text must not be empty for new key.

400

INVALID_REQUEST

None

Message: The custom key you’re trying to create is not in the correct format. Ensure that the correct prefix is provided.

When and details

When: A POST or PUT request supplies a key whose module prefix is not one of the supported modules

Details: None.

400

INVALID_REQUEST

None

Message: The service-specific message describing the violated rule.

When and details

When: A DELETE /translations/en request supplies an empty key list, a non-English language, a module value other than forms, a block value other than customMessages, a key not prefixed with forms., a key longer than 500 characters, or a key that is a default translation key

Details: None. Representative messages: Keys must not be empty., You cannot delete custom keys for Non-English language., Deletion of keys are only supported for the 'forms' module., Deletion of keys are only supported for the 'Custom Messages' Page., The translation key cannot exceed 500 characters., Default translation key=<key> cannot be deleted.

403

ACCESS_FAILED

None

Message: The actor attempting to perform the request is not authorized.

When and details

When: The actor lacks the langmgt:create:language permission (POST), the langmgt:read:language permission (GET operations), the langmgt:update:language permission (PUT), or the langmgt:delete:language permission (DELETE)

Details: None.

404

NOT_FOUND

None

Message: The languageCode=<locale> in a request for environmentId=<environmentID> does not exist. or Unable to find keys for environmentId=<environmentID> with key=forms.<shortKey>

When and details

When: The {locale} path parameter is not a standard language code, or a DELETE /translations/en request supplies keys that do not exist

Details: None.