Manage localization using the API

You can find background information on localization in PingOne Advanced Identity Cloud in Localize tenant admin console and hosted pages.

View all language sets and default language set

Create an access token in either realm that has the fr:idm:* scope.

View all language sets using a GET request with a query filter.

Show request

$ curl -G \
--request GET 'https://<tenant-env-fqdn>/openidm/config/uilocale' \(1)
--header 'Authorization: Bearer <access-token>' \(2)
--data-urlencode '_queryFilter=_id sw "uilocale"'

1	Replace <tenant-env-fqdn> with the domain of your environment. For example, `openam-mycompany.forgeblocks.com`.
2	Replace <access-token> with the access token.

Show response

{
    "result": [
        {
            "_id": "uilocale/de", (1)
            "_meta": {...},
            "admin": {...},
            "login": {...},
            "shared": {...},
            "enduser": {...}
        },
        {
            "_id": "uilocale/defaultLocaleCode", (2)
            "defaultLocale": "de"  (2)
        },
        {
            "_id": "uilocale/fr",  (1)
            "_meta": {...},
            "admin": {...},
            "login": {...},
            "shared": {...},
            "enduser": {...}
        },
        {
            "_id": "uilocale/it", (1)
            "_meta": {...},
            "admin": {...},
            "login": {...},
            "shared": {...},
            "enduser": {...}
        }
    ],
    "resultCount": 4,
    "pagedResultsCookie": null,
    "totalPagedResultsPolicy": "EXACT",
    "totalPagedResults": 4,
    "remainingPagedResults": -1
}

1	The available language sets are German (`de`), French (`fr`), and Italian (`it`).
2	The default language set is German (`de`).

View a language set

View a language set using a GET request that specifies a locale. You don’t need an access token to view the language set.

Show request

$ curl \
--request GET 'https://<tenant-env-fqdn>/openidm/config/uilocale/<locale>' (1) (2)

1	Replace <tenant-env-fqdn> with the domain of your environment. For example, `openam-mycompany.forgeblocks.com`.
2	Replace <locale> with a locale identifier, such as `fr`.

Show response

{
  "_id": "uilocale/fr",
  "admin": {
    "sideMenu": {
      "securityQuestions": "Questions de sécurité"
    },
    "overrides": {
      "EmailAddress": "Adresse e-mail",
      "Name": "Nom",
      "Owners": "Les propriétaires",
      "AppLogoURI": "URI du logo de l’application"
    }
  },
  "login": {
    "login": {
      "next": "Suivant"
    },
    "overrides": {
      "UserName": "Nom d'utilisateur",
      "Password": "Mot de passe",
      "UnabletoresumesessionItmayhaveexpired": "Impossible de reprendre la session. Elle a peut-être expiré."
    }
  },
  "shared": {
    "sideMenu": {
      "dashboard": "Tableau de bord"
    }
  },
  "enduser": {
    "pages": {
      "dashboard": {
        "widgets": {
          "welcome": {
            "greeting": "Bonjour"
          }
        }
      }
    },
    "overrides": {
      "FirstName": "Prénom",
      "LastName": "Nom de famille"
    }
  }
}

When attempting to view the default en translation, no results are returned. To view the default en translation, use the UI package files specified in Language set format.

Create or replace a language set

Create an access token in either realm that has the fr:idm:* scope.

Create or replace a language set using a PUT request that specifies a locale and includes a JSON payload.

Show request

$ curl \
--request PUT 'https://<tenant-env-fqdn>/openidm/config/uilocale/<locale>' \(1) (2)
--header 'Authorization: Bearer <access-token>' \(3)
--header 'Content-Type: application/json' \
--data-raw '{(4)
  "admin": {
    "sideMenu": {
      "securityQuestions": "Questions de sécurité"
    },
    "overrides": {
      "EmailAddress": "Adresse e-mail",
      "Name": "Nom",
      "Owners": "Les propriétaires",
      "AppLogoURI": "URI du logo de l’application"
    }
  },
  "login": {
    "login": {
      "next": "Suivant"
    },
    "overrides": {
      "UserName": "Nom d'\''utilisateur",
      "Password": "Mot de passe",
      "UnabletoresumesessionItmayhaveexpired": "Impossible de reprendre la session. Elle a peut-être expiré."
    }
  },
  "shared": {
    "sideMenu": {
      "dashboard": "Tableau de bord"
    }
  },
  "enduser": {
    "pages": {
      "dashboard": {
        "widgets": {
          "welcome": {
            "greeting": "Bonjour"
          }
        }
      }
    },
    "overrides": {
      "FirstName": "Prénom",
      "LastName": "Nom de famille"
    }
  }
}'

1	Replace <tenant-env-fqdn> with the domain of your environment. For example, `openam-mycompany.forgeblocks.com`.
2	Replace <locale> with a locale identifier. Some examples are: `en` (English) `es` (Spanish) `fr` (French) `en-us` (English - United States) `es-ar` (Spanish - Argentina) `fr-ca` (French - Canada)
3	Replace <access-token> with the access token.
4	Replace the example translation configuration with your own translation configuration. Refer to Language set format and Translating enum values for details on structuring the payload.

Show response

{
  "_id": "uilocale/fr",
  "admin": {
    "sideMenu": {
      "securityQuestions": "Questions de sécurité"
    },
    "overrides": {
      "EmailAddress": "Adresse e-mail",
      "Name": "Nom",
      "Owners": "Les propriétaires",
      "AppLogoURI": "URI du logo de l’application"
    }
  },
  "login": {
    "login": {
      "next": "Suivant"
    },
    "overrides": {
      "UserName": "Nom d'utilisateur",
      "Password": "Mot de passe",
      "UnabletoresumesessionItmayhaveexpired": "Impossible de reprendre la session. Elle a peut-être expiré."
    }
  },
  "shared": {
    "sideMenu": {
      "dashboard": "Tableau de bord"
    }
  },
  "enduser": {
    "pages": {
      "dashboard": {
        "widgets": {
          "welcome": {
            "greeting": "Bonjour"
          }
        }
      }
    },
    "overrides": {
      "FirstName": "Prénom",
      "LastName": "Nom de famille"
    }
  }
}

Create or replace individual language set keys

Create an access token in either realm that has the fr:idm:* scope.

Create or replace individual language set keys using a PATCH request that specifies a locale and includes a JSON payload containing one or more operation objects.

Show request

$ curl \
--request PATCH '<tenant-env-fqdn>/openidm/config/uilocale/<locale>' \(1) (2)
--header 'Authorization: Bearer <access-token>' \(3)
--header 'Content-Type: application/json' \
--data-raw '[
  {
    "operation":"add",
    "field":"<translation-key-name>",(4)
    "value":"<translation-key-value>"(5)
  }
]'

1	Replace <tenant-env-fqdn> with the domain of your environment. For example, `openam-mycompany.forgeblocks.com`.
2	Replace <locale> with a locale identifier. For example, `fr` (French).
3	Replace <access-token> with the access token.
4	Replace <translation-key-name> with the translation key name you want to create or replace. For example, `shared/common/activate`.
5	Replace <translation-key-value> with the translation key value you want to create or replace. For example, `activer`.

Show response

{
  "_id": "uilocale/fr",
  "admin": {
    "sideMenu": {
      "securityQuestions": "Questions de sécurité"
    },
    "overrides": {
      "EmailAddress": "Adresse e-mail",
      "Name": "Nom",
      "Owners": "Les propriétaires",
      "AppLogoURI": "URI du logo de l’application"
    }
  },
  "login": {
    "login": {
      "next": "Suivant"
    },
    "overrides": {
      "UserName": "Nom d'utilisateur",
      "Password": "Mot de passe",
      "UnabletoresumesessionItmayhaveexpired": "Impossible de reprendre la session. Elle a peut-être expiré."
    }
  },
  "shared": {
    "common": {
      "activate": "activer" (1)
    },
    "sideMenu": {
      "dashboard": "Tableau de bord"
    }
  },
  "enduser": {
    "pages": {
      "dashboard": {
        "widgets": {
          "welcome": {
            "greeting": "Bonjour"
          }
        }
      }
    },
    "overrides": {
      "FirstName": "Prénom",
      "LastName": "Nom de famille"
    }
  }
}

1	The response shows the updated language set with a new translation key and value.

Delete a language set

Create an access token in either realm that has the fr:idm:* scope.

Delete the language set using a DELETE request that specifies a locale:

Show request

$ curl \
--request DELETE 'https://<tenant-env-fqdn>/openidm/config/uilocale/<locale>' \(1) (2)
--header 'Authorization: Bearer <access-token>'(3)

1	Replace <tenant-env-fqdn> with the domain of your environment. For example, `openam-mycompany.forgeblocks.com`.
2	Replace <locale> with a locale identifier, such as `fr`.
3	Replace <access-token> with the access token.

Show response

{
  "_id": "uilocale/fr",
  "admin": {
    "sideMenu": {
      "securityQuestions": "Questions de sécurité"
    },
    "overrides": {
      "EmailAddress": "Adresse e-mail",
      "Name": "Nom",
      "Owners": "Les propriétaires",
      "AppLogoURI": "URI du logo de l’application"
    }
  },
  "login": {
    "login": {
      "next": "Suivant"
    },
    "overrides": {
      "UserName": "Nom d'utilisateur",
      "Password": "Mot de passe",
      "UnabletoresumesessionItmayhaveexpired": "Impossible de reprendre la session. Elle a peut-être expiré."
    }
  },
  "shared": {
    "sideMenu": {
      "dashboard": "Tableau de bord"
    }
  },
  "enduser": {
    "pages": {
      "dashboard": {
        "widgets": {
          "welcome": {
            "greeting": "Bonjour"
          }
        }
      }
    },
    "overrides": {
      "FirstName": "Prénom",
      "LastName": "Nom de famille"
    }
  }
}

Update the default language set

Create an access token in either realm that has the fr:idm:* scope.

Update the default language set using a PUT request:

Show request

$ curl \
--request PUT 'https://<tenant-env-fqdn>/openidm/config/uilocale/defaultLocaleCode' \(1)
--header 'Authorization: Bearer <access-token>' \(2)
--header 'Content-Type: application/json' \
--data-raw '{
  "_id": "uilocale/defaultLocaleCode",
  "defaultLocale": "<locale>"(3)
}'

1	Replace <tenant-env-fqdn> with the domain of your environment. For example, `openam-mycompany.forgeblocks.com`.
2	Replace <access-token> with the access token.
3	Replace <locale> with a locale identifier, such as `fr`.

Show response

{
    "_id": "uilocale/defaultLocaleCode",
    "defaultLocale": "fr"
}