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:
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.
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 viacanva.comorcanva.cn."zh", for apps created viacanva.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.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.
- 2.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
}
- 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.
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);
});
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);
});