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:
1
{
2
"en": [
3
{
4
"key": "greeting",
5
"value": "I hope you're having a lovely day.",
6
"translatorNote": "Label for notification when user opens the app."
7
}
8
]
9
}
Copied!
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. 1.
  2. 2.
    Enter the JSON into the JSON instance field.
Alternatively, validate the file against the following JSON Schema as part of your testing workflow:
1
{
2
"properties": {
3
"en": {
4
"type": "array",
5
"items": {
6
"properties": {
7
"key": {
8
"type": "string",
9
"description": "A unique ID for the string."
10
},
11
"value": {
12
"type": "string",
13
"description": "The content of the string."
14
},
15
"translatorNote": {
16
"type": "string",
17
"description": "A note that provides context to assist with translating the string."
18
}
19
},
20
"required": ["key", "value", "translatorNote"],
21
"additionalProperties": false
22
}
23
}
24
},
25
"additionalProperties": false
26
}
Copied!

Step 3: Upload the JSON file

  1. 1.
    Navigate to an app via the Developer Portal.
  2. 2.
    Navigate to an extension that has a Translations field.
  3. 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:
1
canva.onReady(async (opts) => {
2
console.log(opts.localizedLabels);
3
});
Copied!
This parameter is an object, with each key corresponding to the key of a LocalizedLabel.
For example, if the JSON file looks like this:
1
{
2
"en": [
3
{
4
"key": "greeting",
5
"value": "I hope you're having a lovely day.",
6
"translatorNote": "Label for notification when user opens the app."
7
}
8
]
9
}
Copied!
Then this is how the extension gets the value of the "greeting" string:
1
canva.onReady(async (opts) => {
2
console.log(opts.localizedLabels.greeting);
3
});
Copied!
This is an example of a localized label appearing in a Paragraph control:

Example

1
const { imageHelpers } = window.canva;
2
const canva = window.canva.init();
3
4
canva.onReady(async (opts) => {
5
const image = await imageHelpers.fromElement(opts.element);
6
const canvas = await imageHelpers.toCanvas(image);
7
document.body.appendChild(canvas);
8
9
const controls = [
10
canva.create("paragraph", {
11
id: "myExampleParagraph",
12
text: opts.localizedLabels.greeting,
13
}),
14
];
15
16
canva.updateControlPanel(controls);
17
});
Copied!
Last modified 27d ago