> ## 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.
# Migrate an existing app
How to add localization support to an existing app.
This procedure describes how to update an existing app to support Canva’s translation process.
The Canva translation process currently requires use of the `react-intl` library.
## Phase 1: Configure your workspace
This phase explains how to configure your environment to use the recommended i18n tools.
### Step 1: Install prerequisites
1. Install the `react-intl` and `@canva/app-i18n-kit` packages, as well as the latest version of `@canva/app-ui-kit`:
```shell
npm install @canva/app-i18n-kit react-intl @canva/app-ui-kit@latest
```
NOTE: To be able to localize components, your app must use version 4 or later of the [App UI Kit](https://www.canva.dev/docs/apps/app-ui-kit/). Older versions of the App UI Kit don't support localization.
### Step 2: Configure ESLint
This step explains how to configure ESLint for Canva app development. For more information on the rules and configuration options, see the [`@canva/app-eslint-plugin` documentation](https://www.npmjs.com/package/@canva/app-eslint-plugin).
1. Install the `@canva/app-eslint-plugin` package, if not already installed.
```shell
npm install --save-dev eslint @canva/app-eslint-plugin
```
2. Add the recommended shared config to your `eslint.config.mjs`:
```js
import canvaPlugin from "@canva/app-eslint-plugin";
export default [
{
ignores: [
"**/node_modules/",
"**/dist",
"**/*.d.ts",
"**/*.d.tsx",
"**/*.config.*",
],
},
...canvaPlugin.configs.apps,
];
```
### Step 3: Configure FormatJS ID generation
Note: If your app isn't already using `@canva/app-scripts` to build and run your app, we recommend migrating to it. See [the migration guide](https://www.canva.dev/docs/apps/upgrades-and-migrations/app-scripts-migration-guide/) for more information.
If your app uses [`@canva/app-scripts`](https://www.canva.dev/docs/apps/canva-app-scripts/), there's nothing to configure. Both its Rsbuild and webpack adapters already wire in FormatJS message ID generation for you, using a fixed pattern (`[sha512:contenthash:base64:6]`).
If you're adding localization to an app that already has an existing translation catalog generated by a different tool or pattern, re-extract your messages and confirm the IDs still match — a mismatch fails silently until it reaches production. See [the message ID pattern constraint](https://www.canva.dev/docs/apps/upgrades-and-migrations/app-scripts-migration-guide/#formatjs-i18n-and-the-message-id-pattern-constraint) for more detail.
If your app still has its own `webpack.config.js` rather than using `@canva/app-scripts`, configure the FormatJS TS transformer yourself:
1. Add `@formatjs/ts-transformer` to your webpack configuration and install the `@formatjs/cli` package:
```shell
npm install --save-dev @formatjs/ts-transformer @formatjs/cli
```
2. To generate unique message IDs, add a transformer to your `webpack.config.js`. This example adds a function called `getCustomTransformers`:
```json
const { transform } = require("@formatjs/ts-transformer");
// ...
module: {
rules: [
{
test: /\.tsx?$/,
exclude: /node_modules/,
use: [
{
loader: "ts-loader",
options: {
transpileOnly: true,
getCustomTransformers() {
return {
before: [
transform({
overrideIdFn: "[sha512:contenthash:base64:6]",
}),
],
};
},
},
},
],
```
3. In `package.json`, add an `extract` script with the following contents:
```json
formatjs extract \"src/**/*{ts,tsx}\" --out-file dist/messages_en.json
```
Append the extract script to the build script. For example:
```diff
"scripts": {
"start": "tsx «/scripts/start/start.ts",
+ "extract": "formatjs extract \"src/**/*{ts,tsx}\" --out-file dist/messages_en.json",
+ "build": "webpack --config webpack.config.js --mode production && npm run extract",
- "build": "webpack --config webpack.config.js --mode production",
"lint: types": "tsc",
"lint": "eslint .",
"lint:fix": "eslint . --fix",
```
### Step 4: Configure a single-bundle output
Canva's app submission process requires a single app bundle. Implementing localization might increase the size of the app and cause a bundler to split the output into multiple chunks.
If your app uses [`@canva/app-scripts`](https://www.canva.dev/docs/apps/canva-app-scripts/), there's nothing to configure. Both its Rsbuild and webpack adapters already enforce a single-chunk output by default.
If your app still has its own `webpack.config.js`, force webpack to produce a single bundle:
1. Open `webpack.config.js`, and add the `optimize` module to the webpack import:
```diff
- const { DefinePlugin } = require("webpack");
+ const { DefinePlugin, optimize } = require("webpack");
```
2. In `webpack.config.js`, add the chunk limit before `buildDevConfig` is called. Modify [this `plugins` definition](https://github.com/canva-sdks/canva-apps-sdk-starter-kit/blob/82675ff52035eca4645c7652b9dffc25d9e30931/webpack.config.js#L160-L164):
```diff
plugins: [
new DefinePlugin({
BACKEND_HOST: JSON.stringify(backendHost),
}),
+ new optimize.LimitChunkCountPlugin({ maxChunks: 1 }),
],
```
## Phase 2: Updating your app
This phase explains how to update your app to support localization.
### Step 1: Add the dependency
Add `@canva/app-i18n-kit` to your app. You don't need to pass messages or locale into `AppI18nProvider`, because it internally detects the user's locale and loads the appropriate translated messages. In addition, it also lets you test localization in a later step.
```ts
// index.tsx
import { AppUiProvider } from "@canva/app-ui-kit";
import type { DesignEditorIntent } from "@canva/intents/design";
import { prepareDesignEditor } from "@canva/intents/design";
import { createRoot } from "react-dom/client";
import { App } from "./app";
import "@canva/app-ui-kit/styles.css";
import { AppI18nProvider } from "@canva/app-i18n-kit";
async function render() {
const root = createRoot(document.getElementById("root") as Element);
root.render(
,
);
}
const designEditor: DesignEditorIntent = { render };
prepareDesignEditor(designEditor);
```
NOTE: Don't use `IntlProvider` from `react-intl`, since `AppI18nProvider` is a Canva-specific replacement for `IntlProvider`.
### Step 2: Update UI strings
The `react-intl` package lets you use `FormattedMessage` or the `useIntl()` hook. We recommend using `FormattedMessage` wherever possible.
In your app’s code, update the UI strings to use `FormattedMessage`. For example:
```ts
```
If using the `useIntl()` hook:
```ts
const intl = useIntl();
// ...
```
## Phase 3: Testing and release
This phase explains how to test localization in your app and prepare it for release.
### Step 1: Testing localization
The `@canva/app-i18n-kit` package lets you test your app using pseudolocalization and lets you change the locale using the Dev Toolkit. This gives you a preview of what your app could look like in a different locale.
The text lets you read your original English text, but inserts non-ASCII characters and adds width to each string to simulate lengthier languages.
NOTE: This approach is only compatible with our recommended tooling.
1. Enable pseudolocalization in the Dev Toolkit. This shows you a preview of how different characters and text lengths affect the UI:
* Check that any custom components respect the left-to-right and right-to-left setting.
* Make sure there are no rendering issues or truncated text.
NOTE: You can’t preview or test actual translations, since these are only available after your app has been approved. However, you can then preview the translations before releasing your app.
### Step 2: Generate the JSON file
This process extracts all the `FormattedMessage` strings in your code and saves them to a JSON file. You can then upload this file to Canva for translation.
If your app uses [`@canva/app-scripts`](https://www.canva.dev/docs/apps/canva-app-scripts/), extraction runs automatically as part of a build. To generate the `messages_en.json` file, run the following command:
```shell
canva apps build
```
If your app still has its own `webpack.config.js`, run the `extract` script you added in Phase 1:
```shell
npm run extract
```
Once this process has finished, you should see a `messages_en.json` file appear in the `dist` directory, alongside your `app.js`. If this doesn't appear, re-run this step.
### Step 3: Upload the JSON file
As part of the app submission process, you can upload the JSON file for translation:
1. Locate your app in the Developer Portal.
2. Go to **Inside Canva > Code upload**.
3. Under **Translations**, drop the `messages_en.json` file onto the file area, or click **Choose file** to browse for it.
### Next steps
Canva reviews your app and identifies which locales should be supported. Canva then performs the translation of the supplied strings.
You’ll be automatically notified once Canva has finished the translation process. You can then preview your app in the supported locales.
## More information
* Overview of the localization process: [Localization overview](https://www.canva.dev/docs/apps/localization/)
* How to use the recommended workflow: [Recommended workflow](https://www.canva.dev/docs/apps/localization/recommended-workflow/)
* Review the localization design guidelines: [Localization](https://www.canva.dev/docs/apps/design-guidelines/localization/)
* See the supported syntax and exceptions: [ICU syntax](https://www.canva.dev/docs/apps/localization/icu-syntax/)
* See bad practices: [Bad practices](https://www.canva.dev/docs/apps/localization/bad-practices/)