Customize Cord's text

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.

<CordProvider
  translations={{
    en: {
      composer: {
        reply_placeholder: 'Reply...',
      },
    },
    de: {
      composer: {
        reply_placeholder: 'Antworten...',
      },
    },
  }}
>
  <!-- Your application -->
</CordProvider>

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>

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}}.

<CordProvider
  translations={{
    en: {
      message: {
        deleted_message: 'A message was deleted by {{user.displayName}}',
      },
    },
  }}
>
  <!-- Your application -->
</CordProvider>

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>

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. If no string is defined for that key, the key with an _other suffix will used. See the full details in the i18next documentation.

<CordProvider
  translations={{
    en: {
      thread: {
        new_replies_status_one: 'One new reply',
        new_replies_status_other: '{{count}} new replies',
      },
    },
  }}
>
  <!-- Your application -->
</CordProvider>

CordSDK.updateOptions({
  translations: {
    en: {
      thread: {
        new_replies_status_one: 'One new reply',
        new_replies_status_other: '{{count}} new replies',
      },
    },
  },
})

<CordProvider
  translations={{
    en: {
      thread: {
        new_replies_status_one: 'One new reply',
        new_replies_status_other: '{{count}} new replies',
      },
    },
  }}
>
  <!-- Your application -->
</CordProvider>

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.

<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>

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>

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.