> ## 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(); // ...