Localization

Learn how to localize an extension's user-facing text.

In the Developer Portal, some extensions have a Translations field. The presence of this field indicates that you must upload the extension's user-facing strings as a JSON file.

This makes it possible for Canva to:

  • Review the strings before approving the app for release.

  • Translate the strings into 25+ locales. (This only applies to apps created via canva.com, not canva.cn.)

This page explains how to create a JSON file that contains the user-facing strings and how to render those strings via the extension.

If you're creating a public app, you must upload a file to the Translations field. If you're creating a team app, the field is only required for extensions that show notifications.

Step 1: Create a JSON file

The JSON file uploaded to the Translations field must adhere to a specific schema.

This is an example of a valid JSON file:

{
"en": [
{
"key": "greeting",
"value": "I hope you're having a lovely day.",
"translatorNote": "Label for notification when user opens the app."
}
]
}

The top-level property is the language code. For example, "en".

Canva supports two language codes:

  • "en", for apps created via canva.com or canva.cn.

  • "zh", for apps created via canva.cn.

The value of this property is an array of LocalizedLabel objects. Each object describes an individual string that appears in the extension's user interface.

Step 2: Validate the JSON

You can't upload invalid JSON to the Developer Portal, but it's still more convenient to validate the JSON before uploading a file.

To validate the JSON:

  1. Enter the JSON into the JSON instance field.

Alternatively, validate the file against the following JSON Schema as part of your testing workflow:

{
"properties": {
"en": {
"type": "array",
"items": {
"properties": {
"key": {
"type": "string",
"description": "A unique ID for the string."
},
"value": {
"type": "string",
"description": "The content of the string."
},
"translatorNote": {
"type": "string",
"description": "A note that provides context to assist with translating the string."
}
},
"required": ["key", "value", "translatorNote"],
"additionalProperties": false
}
}
},
"additionalProperties": false
}

Step 3: Upload the JSON file

  1. Navigate to an app via the Developer Portal.

  2. Navigate to an extension that has a Translations field.

  3. Upload the JSON file to the Translations field.

If the upload fails, verify the structure of the JSON file.

Step 4: Render the user-facing strings

An extension can access the uploaded strings in the onReady callback, via the opts.localizedLabels parameter:

canva.onReady(async (opts) => {
console.log(opts.localizedLabels);
});

This parameter is an object, with each key corresponding to the key of a LocalizedLabel.

For example, if the JSON file looks like this:

{
"en": [
{
"key": "greeting",
"value": "I hope you're having a lovely day.",
"translatorNote": "Label for notification when user opens the app."
}
]
}

Then this is how the extension gets the value of the "greeting" string:

canva.onReady(async (opts) => {
console.log(opts.localizedLabels.greeting);
});

This is an example of a localized label appearing in a Paragraph control:

Example

const { imageHelpers } = window.canva;
const canva = window.canva.init();
canva.onReady(async (opts) => {
const image = await imageHelpers.fromElement(opts.element);
const canvas = await imageHelpers.toCanvas(image);
document.body.appendChild(canvas);
const controls = [
canva.create("paragraph", {
id: "myExampleParagraph",
text: opts.localizedLabels.greeting,
}),
];
canva.updateControlPanel(controls);
});