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.

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.

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);
});