Localization overview

Canva can translate your app into other languages.

Canva has a large global audience, with most users originating from non-English speaking countries. By localizing your app, you can potentially reach a much larger audience.

To help make your app available in more languages, Canva can perform translations for apps that have successfully completed the app review process.

Canva supports a broad range of locales, while the Apps SDK supports a subset of these locales. These are chosen based on their proportion of Canva’s users.

The supported locales are:

  • Turkish: tr-TR
  • Japanese: ja-JP
  • Korean: ko-KR
  • German: de-DE
  • French: fr-FR
  • Portuguese: pt-BR
  • Indonesian: id-ID
  • Spanish: es-ES and es-419

The Canva translation process currently requires use of the react-intl library.

To internationalize your app, add the react-intl library to your project. This lets you use FormattedMessage components for the UI text, using US English.

  1. Extract the UI strings into a JSON file and upload it as part of the review process.

  2. When your app is approved, Canva identifies which languages are needed and performs the translation. This process also translates the app name, description, among others. Note that Canva translates the strings for you, and you can’t provide your own translations.

  3. Test your app with the new locales and release it when you're ready. For more information, see Testing localization.

  4. Users with a matching Canva language setting will automatically see the app in their language.

    If their language is unavailable, the app can fallback to a similar language, otherwise it will default to English.

Translated strings are only supplied to your frontend JS code, so you should avoid displaying strings directly from the backend. Instead, have the backend return a status code or other response data. The UI can then use this to display an appropriate FormattedMessage.

Our design guidelines help you create a high-quality app that easily passes app review.

The Canva translation process supports a subset of the International Components for Unicode (ICU) MessageFormat syntax. We recommend using ICU because it allows you to capture grammatical elements that may differ between languages, such as plurals and correct placement of placeholders within a sentence.

For more information about the supported ICU syntax with recommendations and examples, see ICU syntax.

To assist Canva’s translators, you can include notes that describe the purpose and context of each string. This information is stored in the description property for each FormattedMessage and is made available to the translators.

  • If space is limited or characters are restricted:

    Specify the maximum number of characters. If possible, allocate more space for the string than the English text requires, because many languages are lengthier than English and need more space than the source string.

    <FormattedMessage
    defaultMessage="Continue with work email"
    description="Option for the user to continue the login process using an email associated with their job. Max. number of characters: 32"
    />
    ts
  • If a word can have more than one meaning:

    Specify the intended meaning. Some words can be used as either a verb or a noun. The translator needs context to disambiguate the term.

    <FormattedMessage
    defaultMessage="Translate"
    description="This is the name of the Canva app. It is a noun."
    />
    ts
    <FormattedMessage
    defaultMessage="Translate"
    description="This is the label on a button to translate the design content. It is a verb."
    />
    ts

If you have strings that shouldn’t be localized, then you can exclude them from the translation process by not putting them within the FormattedMessage component. This means that the string won’t be included in the extracted JSON file. In addition, you must use an ESLint directive to ignore the rule which would usually prevent you from hard-coding English text. For example:

// eslint-disable-next-line no-literal-string-in-jsx
<Text>Text that must not be translated</Text>
typescript

When your app has been translated and released, Canva will identify the locale for the current user and supply the best supported translations it has for your app.

For example, if your app has "Standard" language translation and the user's language is Canadian French (fr-CA), Canva will fallback to the best supported translations, which will be French (fr-FR).

If Canva can't find translations for a user's preferred language and there are no fallbacks available, then the app always falls back to English en.

Localization isn't available for team apps, and there might be other situations where you might not want to localize your app.

In these situations, we recommend you do the following to develop your app without localization:

  1. Disable ESLint rules related to localization. For example:

    {
    "rules": {
    "formatjs/no-invalid-icu": "off",
    "formatjs/no-literal-string-in-jsx": "off",
    "formatjs/enforce-description": "off",
    "formatjs/enforce-default-message": "off",
    "formatjs/enforce-placeholders": "off",
    "formatjs/no-id": "off",
    "formatjs/no-emoji": "off",
    "formatjs/no-useless-message": "off",
    "formatjs/no-multiple-plurals": "off",
    "formatjs/no-offset": "off",
    "formatjs/blocklist-elements": "off",
    "formatjs/no-complex-selectors": "off"
    }
    }
    json
  2. Remove npm libraries for localization:

    npm uninstall react-intl @formatjs/cli @formatjs/ts-transformer @canva/app-i18n-kit
    shell
  3. Remove all code related to the localization libraries. For example, remove any usage of AppI18nProvider, FormattedMessage, and others.