Localization

Search…
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.Navigate to jsonschema.dev/s/NoKxh.
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
}
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);
});
Frontend development - Previous
Error handling
Next - Frontend development
Notifications
Last modified 10mo ago
Copy link
Outline
Step 1: Create a JSON file
Step 2: Validate the JSON
Step 3: Upload the JSON file
Step 4: Render the user-facing strings
Example