Customize Cord's UI text

Translate Cord to another language or change the text of components


Introduction #

Cord's SDK comes with a translation framework that allows you to replace the strings in Cord components. You can use this to replace Cord's default messages and labels with ones of your own or translate the SDK into another language.

We use the popular i18next framework to handle our translations, so if you're familiar with it, you'll be right at home with our system.

Basic Usage #

  • Change the strings using the translations configuration option to the SDK's initialization.
  • Each string in the SDK has an identifier, and they're organized into namespaces (such as composer or message) that give you a clue as to where they'll be used.
  • The default language is en (English), so to change the default values, set new values for the en language.
  • You can specify as many or as few of the strings as you want, with anything that's unspecified falling back to Cord's default value, so you can override only the strings you need to.
💡 To see the strings we support, you can browse the default values in our open source repository.
React:
<CordProvider
  translations={{
    en: {
      composer: {
        reply_placeholder: 'Reply...',
      },
    },
    de: {
      composer: {
        reply_placeholder: 'Antworten...',
      },
    },
  }}
>
  <!-- Your application -->
</CordProvider>
Vanilla JavaScript:
CordSDK.updateOptions({
  translations: {
    en: {
      composer: {
        reply_placeholder: 'Reply...',
      },
    },
    de: {
      composer: {
        reply_placeholder: 'Antworten...',
      },
    },
  },
})
<CordProvider
  translations={{
    en: {
      composer: {
        reply_placeholder: 'Reply...',
      },
    },
    de: {
      composer: {
        reply_placeholder: 'Antworten...',
      },
    },
  }}
>
  <!-- Your application -->
</CordProvider>
Copy

Interpolation #

Some strings need to have values filled in, such as a user's name or the number of unread replies. These are placed into the string with {{double braces}}.

React:
<CordProvider
  translations={{
    en: {
      message: {
        deleted_message: 'A message was deleted by {{user.displayName}}',
      },
    },
  }}
>
  <!-- Your application -->
</CordProvider>
Vanilla JavaScript:
CordSDK.updateOptions({
  translations: {
    en: {
      message: {
        deleted_message: 'A message was deleted by {{user.displayName}}',
      },
    },
  },
})
<CordProvider
  translations={{
    en: {
      message: {
        deleted_message: 'A message was deleted by {{user.displayName}}',
      },
    },
  }}
>
  <!-- Your application -->
</CordProvider>
Copy

For any string that uses a user, the user object will have all the fields returned by the User API. In particular, you can use the user's metadata to store any additional information that you want to use in your strings, such as additional name components or pronouns.

Plurals #

When a count of items is shown, the identifier for the string will be appended with an appropriate suffix, such as _zero or _one, to allow customizing based on the language's pluralization rules. See the full details in the i18next documentation.

You need to supply a message for every suffix used in the language, otherwise missing forms will fall back to English text. You can use the below tool to see all the suffixes you need to supply for each language.

Language code:
Plural suffixes needed: _one, _other

React:
<CordProvider
  translations={{
    en: {
      thread: {
        new_replies_status_one: 'One new reply',
        new_replies_status_other: '{{count}} new replies',
      },
    },
    he: {
      thread: {
        new_replies_status_one: 'תגובה חדשה אחת',
        new_replies_status_two: '⁧2 תגובות חדשות⁩',
        new_replies_status_other: '⁧{{count}} תגובות חדשות⁩',
      },
    },
  }}
>
  <!-- Your application -->
</CordProvider>
Vanilla JavaScript:
CordSDK.updateOptions({
  translations: {
    en: {
      thread: {
        new_replies_status_one: 'One new reply',
        new_replies_status_other: '{{count}} new replies',
      },
    },
    he: {
      thread: {
        new_replies_status_one: 'תגובה חדשה אחת',
        new_replies_status_two: '⁧2 תגובות חדשות⁩',
        new_replies_status_other: '⁧{{count}} תגובות חדשות⁩',
      },
    },
  },
})
<CordProvider
  translations={{
    en: {
      thread: {
        new_replies_status_one: 'One new reply',
        new_replies_status_other: '{{count}} new replies',
      },
    },
    he: {
      thread: {
        new_replies_status_one: 'תגובה חדשה אחת',
        new_replies_status_two: '⁧2 תגובות חדשות⁩',
        new_replies_status_other: '⁧{{count}} תגובות חדשות⁩',
      },
    },
  }}
>
  <!-- Your application -->
</CordProvider>
Copy

Changing Languages #

To change the language of the SDK, set the language configuration option to the language code of your choice. The SDK only ships with values for en (English), so for any other language, you'll need to supply all the translations. Any strings that don't have a value for that language will fall back to the en string.

Language dialects and scripts are supported, and will fall back to the base language if a string is not available in that language, so you can avoid specifying the same string in more than one place.

React:
<CordProvider
  translations={{
    en: {
      thread: {
        placeholder_title: 'Socialize here!',
        placeholder_body: 'This is the place to send messages to your friends.',
      },
    },
    'en-GB': {
      thread: {
        placeholder_title: 'Socialise here!',
      },
    },
  }}
>
  <!-- Your application -->
</CordProvider>
Vanilla JavaScript:
CordSDK.updateOptions({
  translations: {
    en: {
      thread: {
        placeholder_title: 'Socialize here!',
        placeholder_body: 'This is the place to send messages to your friends.',
      },
    },
    'en-GB': {
      thread: {
        placeholder_title: 'Socialise here!',
      },
    },
  },
})
<CordProvider
  translations={{
    en: {
      thread: {
        placeholder_title: 'Socialize here!',
        placeholder_body: 'This is the place to send messages to your friends.',
      },
    },
    'en-GB': {
      thread: {
        placeholder_title: 'Socialise here!',
      },
    },
  }}
>
  <!-- Your application -->
</CordProvider>
Copy
⚠️ Our components don't currently adapt their layout for right-to-left languages, so while you can specify translations for those languages, the result may not look ideal.
💡 You can set the language to the special value cimode to replace all strings with their identifiers.

Customizing Messages #

In some cases, you may want to customize the content of a message inside a thread. For example, when a user resolves a thread, Cord inserts an action message saying who resolved the thread, and you can customize that text.

To support this, messages have a translationKey property. When a message with a translation key is rendered, that key is looked up in the message_templates namespace, and if a translation is present, it will be used rather than the content of the message object. This translation can be either a plain string or a structured message object.

Any mentions in the message content will be passed in values named message1 through messageN based on their position in the message, to allow you to use them in the message. See the existing translations in the message_templates namespace for examples.

Ask Cordy