ICU syntax

The Canva translation process supports a subset of ICU MessageFormat syntax. For more information about ICU, see the official FormatJS documentation⁠(opens in a new tab or window).

This section describes the supported ICU syntax, with recommendations and examples.

Follow these examples and guidelines so that your app can be translated more accurately and efficiently.

How to do basic message localization with React, using the FormattedMessage component from react-intl.

• The defaultMessage string is the source for translation text. It's displayed to users that either have an English locale, or a locale with no translations available.
• Use the description string to give as much context as possible to a human translator. For guidance on writing translator notes, see Add notes for translators.

For example:

<FormattedMessage
  defaultMessage="My internationalized app"
  description="The title the user sees when opening the app. Appears at top of page."
/>

You can use dynamic values (like firstName) in the defaultMessage prop of FormattedMessage. This process is known as interpolation.

This section explains how to use interpolation for localized messages in React, using the FormattedMessage component from react-intl.

For example:

const name = "John"
// ...
<FormattedMessage
  defaultMessage="Welcome to the world of AI creativity, {firstName}!"
  description="A greeting that welcomes the user to the AI image generation app"
  values={{
    firstName: name,
  }}
/>

This renders as: "Welcome to the world of AI creativity, John!"

How to handle plurals in localized messages in React.

For example:

export const CreditUsage = ({
  creditsCost,
  remainingCredits,
}: {
  creditsCost: number;
  remainingCredits: number;
}) => (
  <Text>
    <FormattedMessage
      defaultMessage={`Use {creditsCost, number} of {remainingCredits, plural,
        one {# credit}
        other {# credits}
      }`}
      description="Informs the user about the number of credits they will use for the image generation task. Appears below the image generation button."
      values={{
        creditsCost,
        remainingCredits,
      }}
    />
  </Text>
);

<CreditUsage creditsCost={5} remainingCredits={50} />
<CreditUsage creditsCost={1} remainingCredits={1} />

This would render as:

• "Use 5 of 50 credits"
• "Use 1 of 1 credit"

To localize numbers for the user's locale, ICU needs them to be formatted with a specific argument.

This example shows how to format numbers in localized messages in React, using the FormattedMessage component from react-intl.

<FormattedMessage
  defaultMessage="Image generation is {progress, number, ::percent} complete."
  description="Displays the progress of the current image generation task that the user requested"
  values={{
    progress: 0.75,
  }}
/>

Assuming the locale uses this percentage format, this can render as: "Image generation is 75% complete."

Automatically adjusts currency symbols and formats based on the user's locale. This function does not convert currency into other denominations, and does not consider exchange rates at any point.

• ::currency/CODE: Specifies the currency code for number formatting (such as USD, EUR).

In this example, the number 1234.56 is formatted as currency in USD, displaying "$1,234.56" for locales using the dollar sign format. The ::currency/USD syntax configures the number formatting for the specified currency.

<FormattedMessage
  defaultMessage="The total amount is {amount, number, ::currency/USD}"
  description="Displays the total amount in USD currency"
  values={{
    amount: 1234.56,
  }}

Rendered result: The total amount is $1,234.56

Automatically adjusts decimal number formats based on the user's locale.

• {temperature, number, .0}: Formats the number as a decimal with one fractional digit.

This example shows how to display a temperature reading. The {temperature, number, .0} syntax formats the number 23.456 as "23.5", representing the temperature with one decimal place.

<FormattedMessage
  defaultMessage="The current temperature is {temperature, number, .0} degrees."
  description="Displays the current temperature with one decimal place"
  values={{
    temperature: 23.456,
  }}
/>

Rendered result: The current temperature is 23.5 degrees.

Automatically adjusts percentage formats based on the user's locale.

• {progress, number, ::percent}: Formats a number as a percentage.

This example shows how to display task completion progress. The {progress, number, ::percent} syntax formats the number 0.71 as "71%", representing the progress in whole percentage terms.

<FormattedMessage
  defaultMessage="Task completion is at {progress, number, ::percent}."
  description="Displays the task completion progress as a full percentage"
  values={{
    progress: 0.71,
  }}
/>

Rendered result: Task completion is at 71%.

To localize date values for the user's locale, ICU needs them to be formatted with a specific argument.

This example demonstrates how to format dates and times in localized messages in React, using the FormattedMessage component from react-intl.

<FormattedMessage
  defaultMessage="Credits refresh on: {refreshDate, date, short} at {refreshTime, time, short}"
  description="Informs users when their credits for image generation will refresh, including the time"
  values={{
    refreshDate: new Date("2023-11-24T15:00:00"),
    refreshTime: new Date("2023-11-24T15:00:00"),
  }}
/>

Depending on the user's locale, this can render as: Credits refresh on: 11/24/23 at 3:00 PM".

To localize time values for the user's locale, ICU needs them to be formatted with a specific argument.

This section provides guidelines for displaying relative time.

const LastGeneratedMessage = ({
  lastGeneratedTime,
}: {
  lastGeneratedTime: Date;
}) => {
  const intl = useIntl();

  const [generatedTimeAgoInSeconds, setGeneratedTimeAgoInSeconds] = React.useState(0);

  // ...

  return (
    <Text>
      <FormattedMessage
        defaultMessage="Last image generated {timeAgo}"
        description="Tells the user how long ago they generated their last image. timeAgo is a relative time string. e.g. '5 seconds ago'"
        values={{
          timeAgo: intl.formatRelativeTime(
            -generatedTimeAgoInSeconds,
            "seconds",
          ),
        }}
      />
    </Text>
  );
};

If your message needs to adapt to a specific, categorical value (such as status or day) and an obvious fallback value, then select might be easier to implement than interpolation. Select lets you define the various message strings directly within the message format, making your code more concise and easier to maintain. While select might appear simpler and preferable to implement at first, it can become more complex once you start nesting ICU elements.

Interpolation is more familiar to JavaScript and TypeScript developers and is a flexible and powerful option, especially when you need to handle multiple dynamic values.

The following table summarizes the use cases for select and interpolation.

These examples compare how select and interpolation would handle a dynamic greeting:

Select:

When using select, you can create a message that changes based the document type:

Here are your stats for the year. {doctype, select, presentation{Your slides are the talk of the town!} social {Your followers love your work!} other {Way to go!}}

Interpolation:

When using string interpolation instead of select, you need to define logic outside the message to choose the appropriate string for the doctype. Here's and example of how the interpolation code might look:

import { defineMessages, useIntl } from 'react-intl';

const messages = defineMessages({
  presentation: { 
    defaultMessage: "Your slides are the talk of the town!", 
    description: "Message for presentation documents" 
  },
  social: { 
    defaultMessage: "Your followers love your work!", 
    description: "Message for social media posts" 
  },
  other: { 
    defaultMessage: "Way to go!", 
    description: "Fallback message" 
  },
});

const interpolateSelect = (key, intl) => {
  return intl.formatMessage(messages[key] || messages.other);
};

const DocumentMessage = ({ doctype }) => {
  const intl = useIntl();
  const message = interpolateSelect(doctype, intl);

  return <p>{message}</p>;
};

// Usage example
<DocumentMessage doctype="presentation" />

How to format rich text in localized messages in React, using the FormattedMessage component from react-intl.

For example:

<FormattedMessage
  defaultMessage="Discover stunning AI-generated example images in our <link>gallery</link> and <callToAction>start exploring now!</callToAction>"
  description="A call to action directing the user to explore the AI image gallery"
  values={{
    link: (chunks) => (
      <Link
        href={DOCS_URL}
        requestOpenExternalUrl={() => openExternalUrl(DOCS_URL)}
      >
        {chunks}
      </Link>
    ),
    callToAction: (chunks) => <strong>{chunks}</strong>,
  }}
>
  {(chunks) => <Text>{chunks}</Text>}
</FormattedMessage>

This can render as: "Discover stunning AI-generated example images in our gallery and start exploring now!"

How to use localized strings as button labels in React, using formatMessage from react-intl.

For example:

<Button variant="primary">
  {intl.formatMessage({
    defaultMessage: "Generate image",
    description: "A button label to generate an image from a prompt",
  })}
</Button>

This renders a button with the label "Generate image", and the text is localized based on the user's locale.

How to use non-visible text for accessibility purposes (such as screen reader descriptions) in React, using ariaLabel and formatMessage from react-intl.

For example:

<Button
  variant="primary"
  icon={SortIcon}
  ariaLabel={intl.formatMessage({
    defaultMessage: "Sort images by creation date (Newest to Oldest)",
    description:
      "Screenreader text for a button. When pressed, the button will sort the generated images by creation date from newest to oldest.",
  })}
/>

The screen reader will read the aria label as: "Sort images by creation date (Newest to Oldest)".

To support left-to-right (LTR) and right-to-left (RTL) languages, you can use CSS properties in UI components.

This example uses paddingStart instead of paddingLeft or paddingRight, which lets your UI automatically adapt to the language's text direction.

<Box paddingStart="2u">
  <Slider min={0} max={100} />
</Box>

How to format lists in a way that is compatible with localization.

In this example, the SelectedEffects component defines a list of image effects, each formatted for localization.

const SelectedEffects = () => {
  const intl = useIntl();

  // TODO: Make this list change based on user selection!
  const selectedEffects = [
    intl.formatMessage({
      defaultMessage: "black and white",
      description:
        "An option that when selected, will apply a black and white effect to the generated image",
    }),
    intl.formatMessage({
      defaultMessage: "high contrast",
      description:
        "An option that when selected, will apply a high contrast effect to the generated image",
    }),
    intl.formatMessage({
      defaultMessage: "cartoon",
      description:
        "An option that when selected, will apply a cartoon effect to the generated image",
    }),
  ];

  return (
    <Text>
      <FormattedMessage
        defaultMessage="You have selected the following image effects: {effects}"
        description="Informs the user about the image effects they have selected. effects is a list of effects that will be applied to the generated image."
        values={{
          effects: intl.formatList(selectedEffects, {
            type: "conjunction",
          }),
        }}
      />
    </Text>
  );
};

This component renders based on the user's locale. For example, an English list uses an Oxford comma, but German does not:

• English (en-US): "You have selected the following image effects: black and white, high contrast, and cartoon."
• German (de-DE): "Sie haben die folgenden Bildeffekte ausgewählt: Schwarzweiß, hoher Kontrast und Cartoon."

How to use display name formatting to inform users about the app's active language, using the FormattedMessage component with React.

For example:

<FormattedMessage
  defaultMessage="You are currently viewing this app in {language}"
  description="Shows the user which language the app is currently using"
  values={{
    language: intl.formatDisplayName(intl.locale, {
      type: "language",
    }),
  }}
/>

{firstChoice, select,
  optionA {First A}
  optionB {First B}
  other {First C}
} {secondChoice, select,
  optionX {Second X}
  optionY {Second Y}
  other {Second Z}
} {thirdChoice, select,
  option1 {Third 1}
  option2 {Third 2}
  other {Third 3}
}

{gender, select, 
  male {
    {count, plural, 
      one {He has one item} 
      other {He has # items}
    }
  } 
  other {
    {count, plural, 
      one {They have one item} 
      other {They have # items}
    }
  }
}

{task_count, plural,
  one {
    You have {# task_count} task: {task_name}.
  }
  other {
    You have {# task_count} tasks. Next task: {task_name}.
  }
}

• Overview of the localization process: Localization overview
• How to use the recommended workflow: Recommended workflow
• How to localize an existing app: Migrate an existing app
• Review the localization design guidelines: Localization