Enables you to create string elements that can serve as the text for items such as labels, tips, and placeholders. For example, the screenshot shown above includes the following translatable string:

After you submit your registration information, we'll text you an access code. You'll use that code to complete the registration and log on to the site.

Note that the translatable string falls into a sort of “gray zone” when it comes to Identity Cloud fields. If you use the Console’s Registration Builder you’ll see Translatable String as one of the available options when creating a field:

However, to create a translatable string by using the Configuration API, you don’t use the /flows/{flowId}/fields operation employed to create other Identity Cloud field types; instead, you use the /flows/{flowId}/translations operation. In addition to that, when you create a translatable string by using that operation there’s no way to specify a name for your new string: translatable strings created with the Configuration API are identified only by their id. That means that these strings can’t be accessed by using Registration Builder (which relies on names rather than IDs). 

📘

Just to clarify, you can include the name property when making an API call. However, this name is ignored when you make the API call, and the translation will not be given a name.

The long and short of it? If you create a translatable string in Registration Builder, that string can be used in Registration Builder (obviously) or by the Configuration API (although you’ll need to manage the field by using the string id). If you create a translatable string by using the API, that string can only be used by the API (because it doesn’t have a name, which renders it invisible to Registration Builder). We recommend using Registration Builder to construct your strings, simply because it offers more flexibility, but that’s entirely up to you.

Translatable string attributes and terminology

The translatable string field, like other Identity Cloud fields, provides a number of attributes you can use when creating and formatting the field. Also like other Identity Cloud fields, the terminology used to represent these attributes in Console’s Registration Builder sometimes differs from the terminology required when using the Configuration APIs which, in turn, sometimes differs from the terminology used if you view the underlying flow. 

Needless to say, that can be confusing at times. With that in mind, the following table shows the different translatable string attributes and how they are referenced in Registration Builder, the Configuration API, and the flow; click the appropriate link in the flow column for more information about that attribute. Attributes highlighted in yellow are auto-generated when the field is created, and shouldn’t be referenced when making an API call (and can’t be accessed in Registration Builder).

Create a translatable string field by using the Configuration API

If you’re using the Configuration APIs to create a translatable string, you must include all the desired attributes and attribute values within the request body of your API call. That request body will look similar to one shown below (depending, of course, on the number of attributes you use):

[
  {
    "values": {
      "en-US": "This is a new translation."
     }
  }
]

If you’re using Postman, your request body will look like this:

As you can see, the syntax for creating a translatable string by using the Configuration API is remarkably easy: just be sure to specify the language code (e.g., en-US) for the new string. If you want to create multiple translations with a single API call, that’s fine:

[
  {
    "values": {
      "en-US": "This is a new translation."
     }
  },
 {
   "values": {
   "en-US": "This is another new translation."
   }
 },
]

You can also specify multiple languages within the same API call:

{
    "values": {
      "en-US": "This is a new translation.",
      "fr-FR": "Ceci est une nouvelle traduction."
     }
  },

A complete Curl command for creating a translatable string will look similar to this:

curl -L -X POST \
  'https://v1.api.us.janrain.com/config/79y4mqf2rt3bxs378kw5479xdu/flows/fieldExamples/translations' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic eTR4Zmc2ZjQ0bXNhYzN2ZXBqanZ4Z2d6dnQzZTNzazk6OTVjY3hrN2N6YnZ1eng2ZHB0ZTVrOXA2ZGo1Ynpla3U=' \
  --data-raw '[
    {
      "values": {
        "en-US": "This is a new translation."
      }
    }
  ]
'