> ## Documentation Index
> Fetch the complete documentation index at: https://www.canva.dev/docs/apps/llms.txt
> Use this file to discover all available pages before exploring further.

# Bad practices

Common localization mistakes to avoid and how to fix them.

Bad localization practices can result in a confusing mix of languages, inconsistent user experiences and reduced user engagement with your app. This page outlines common mistakes (bad practices) when localizing your app, and how to avoid them to make sure a consistent, high-quality experience for all users.

## Bad practices when localizing app UI strings

When App UI strings aren't properly localized, it often results in unexpected untranslated content like shown in the image below. This section outlines the most common bad practices.

### Not setting up i18n linting

<DontText>**Don't** skip setting up the recommended i18n linting configuration or ignore linting errors.</DontText>

<DoText>**Do** set up the recommended i18n linting and fix all linting errors. See [Step 2: Configure ESLint](https://www.canva.dev/docs/apps/localization/migrate-an-existing-app/#step-2-configure-eslint).</DoText>

### Unformatted strings

<DontText>**Don't** render strings without localizing them first.</DontText>

```jsx
<Text>Welcome to My App</Text>
<Select
  placeholder="Select an option"
  options={[
    { label: "Option 1", value: "option1" },
    { label: "Option 2", value: "option2" },
  ]}
/>
<Button ariaLabel="Select an option" />
```

<DoText>**Do** use `intl.formatMessage` or `<FormattedMessage>` for any user-facing text.</DoText>

```jsx
<Text><FormattedMessage defaultMessage="Welcome to My App" /></Text>
<Select
  placeholder={intl.formatMessage({ defaultMessage: "Select an option" })}
  options={[
    { label: intl.formatMessage({ defaultMessage: "Option 1" }), value: "option1" },
    { label: intl.formatMessage({ defaultMessage: "Option 2" }), value: "option2" },
  ]}
/>
<Button ariaLabel={intl.formatMessage({ defaultMessage: "Select an option" })} />
```

If you need to make an exception (e.g. brand names), see [Excluding text](https://www.canva.dev/docs/apps/localization/#excluding-text).

### Use dynamic `id` or `defaultMessage` values

<DontText>**Don't** use dynamic <code>id</code> values in your messages. `@formatjs/cli` won't extract these messages for translation.</DontText>

```jsx
<FormattedMessage id={menuItemKey} />
<FormattedMessage id={`menu.${menuItemKey}`} />
// OR
intl.formatMessage({ id: menuItemKey })
intl.formatMessage({ id: `menu.${menuItemKey}` })
```

<DontText>**Don't** use dynamic <code>defaultMessage</code> values in your messages. `@formatjs/cli` won't extract these messages for translation.</DontText>

```jsx
<FormattedMessage defaultMessage={menuItemLabel} />
<FormattedMessage defaultMessage={`Menu: ${menuItemLabel}`} />
// OR
intl.formatMessage({ defaultMessage: menuItemLabel })
intl.formatMessage({ defaultMessage: `Menu: ${menuItemLabel}` })
```

<DoText>**Do** use predefined messages and select the message based on a dynamic value. `@formatjs/cli` will correctly extract these messages for translation.</DoText>

```jsx
const menuMessages = defineMessages({
  edit: {
    defaultMessage: "Edit"
  },
  view: {
    defaultMessage: "View"
  },
  // Add more menu items ...
});

function getMenuMessage(menuItemKey) {
  switch (menuItemKey) {
    case "edit":
      return menuMessages.edit;
    case "view":
      return menuMessages.view;
    // Add more menu items ...
    default:
      throw new Error(`Unknown menu item: ${menuItemKey}`);
  }
}

<FormattedMessage {...getMenuMessage(selectedMenuItem)} />
```

### Render strings returned from the backend

<DontText>**Avoid** rendering untranslated strings returned directly from your backend. Instead, map backend responses to predefined messages on your frontend, so you can use translations provided by Canva.</DontText>

```jsx
<Text>{response.errorMessage}</Text>
```

<DoText>**Do** map backend responses to predefined messages on the frontend.</DoText>

```jsx
const messages = defineMessages({
  inappropriateContent: {
    defaultMessage: "Inappropriate content detected."
  },
  // Add more messages ...
  unknownError: {
    defaultMessage: "An unknown error occurred. Modify your request and try again."
  }
});

function getErrorMessage(errorCode) {
  switch (errorCode) {
    case "INAPPROPRIATE_CONTENT":
      return messages.inappropriateContent;
    // Add more messages ...
    default:
      return messages.unknownError;
  }
}

<FormattedMessage {...getErrorMessage(response.errorCode)} />
```

See [Preferred: Frontend localization](https://www.canva.dev/docs/apps/localization/backend-responses/#preferred-frontend-localization) for a more complete example.

### Define placeholder-only messages

<DontText>**Avoid** defining messages that only contain variable placeholders. This is problematic, because once this message is extracted into your  `messages_en.json` file, it will only contain the variable placeholder without any other text, and as such nothing will be translated.</DontText>

```jsx
<FormattedMessage
  defaultMessage="{selectedOption}"
  values={{ selectedOption }}
/>
```

<DoText>**Do** define a static message for each possible value, so that each value is translated.</DoText>

```jsx
const optionMessages = defineMessages({
  apple: {
    defaultMessage: "Apple"
  },
  banana: {
    defaultMessage: "Banana"
  }
  // ...
});

function getOptionMessage(optionKey) {
  switch (optionKey) {
    case "apple":
      return optionMessages.apple;
    case "banana":
      return optionMessages.banana;
    // ...
    default:
      throw new Error(`Unknown option: ${optionKey}`);
  }
}

<FormattedMessage {...getOptionMessage(selectedOption)} />
```

For guidance on when and how to use interpolation, follow [this guide](https://www.canva.dev/docs/apps/localization/icu-syntax/#interpolation).