How to Translate Your Course with JSON

Use AI to translate your Embedin course interface with a copyable JSON template. Follow a ready-to-use prompt, review the results, and import your labels.

How to Translate Your Course with JSON

Your course should sound like you, including the small details: sign-in buttons, enrollment messages, quiz results, and the welcome screen learners see before a cohort starts.

In Embedin, you can customize these labels one at a time or paste a JSON object to update several at once. The Import JSON panel includes a copyable template, checks your input, and fills in the translation form for you.

This tutorial walks through copying the template, using AI to draft translations, reviewing the results, and applying only the changes you want. You can also translate the values yourself or work with a translator.

What this feature translates

The Translations & learner copy page controls learner-facing interface text for a course, including:

  • Sign-in and enrollment prompts.
  • Navigation labels and session messages.
  • Course availability messages.
  • Cohort welcome text, countdown labels, and lesson release messages.
  • Quiz results, completion messages, and review prompts.

It does not translate lesson content, rename your modules, or translate student posts.

Custom text applies to all learners of that course. Importing Spanish text, for example, does not create a separate Spanish version or automatically switch languages based on the learner's browser. Fields without an override use the built-in English text.

1. Open your course's translations

Sign in to Embedin, open the course you want to customize, and select Translations in the course menu.

The page heading is Translations & learner copy. You can browse its sections, search for a particular label, or filter to see only customized fields.

Select Import JSON to open the paste panel.

2. Copy the JSON template

Expand JSON template below the text area, then select Copy template.

The button changes to Copied! after copying succeeds. The template contains every field available on the page, using its translation key and example English text.

If your browser blocks clipboard access, the panel shows a manual-copy instruction. You can select the displayed JSON and copy it yourself.

Paste the template into a text editor to choose which fields to update. You can then give those fields to an AI assistant or share them with the person preparing your translations.

3. Translate the values, not the keys

JSON represents each translation as a key and a text value:

{
  "ctaLoginButtonText": "Entrar",
  "ctaEnrollButtonText": "Inscribirme",
  "cohortWelcomeTitle": "Tu curso comienza pronto",
  "cohortStartsOn": "Comienza el {date}",
  "cohortLessonOpens": "Disponible el {date}.",
  "cohortInstructor": "Tu instructor",
  "cohortMeet": "Conoce a tu grupo"
}

In this example, ctaLoginButtonText stays unchanged because it identifies the sign-in button. Only its value changes to Entrar.

Use the exact keys from the template. Do not translate their spelling or capitalization, and keep every value inside double quotes.

Remove any keys you do not want to update. Applying the complete template replaces every included field with the value you paste, even if that value is still English.

Use AI to prepare a first draft

Open an AI assistant approved for your work. Copy the prompt below, change Spanish (Spain) to your target language and locale, and replace the final line with the JSON you copied from Embedin.

Translate only the string values in the JSON below into Spanish (Spain).
Use a friendly, clear tone for an online course interface.

Rules:
- Keep every JSON key exactly as written, including capitalization.
- Keep all placeholder tokens exactly as written, including {date},
  {score}, {passingScore}, and {domain}. You may move them within a sentence.
- Keep brand names such as Embedin unchanged.
- Use consistent terminology for lessons, cohorts, and enrollment.
- Do not add or remove keys, and keep every value a string.
- Return only a valid, flat JSON object, with no Markdown code fences,
  comments, explanations, or surrounding translations property.

JSON:
[Paste your copied JSON here]

For a more tailored result, describe your preferred tone or terminology before the JSON. For example: "Use informal language and call the instructor a mentor." A specific locale, such as Portuguese (Brazil), is more useful than just naming a language.

Share only the interface text needed for translation. The template does not need learner information, credentials, or private lesson content. Follow your organization's policy for the AI tool you use.

Review the AI output before importing

AI translations are drafts, not a guarantee of accuracy. Before applying the result:

  • Confirm that the keys are unchanged and only the fields you want are included.
  • Check that all placeholders survived exactly, including their braces and capitalization.
  • Read buttons and messages for meaning, tone, and consistent terminology. Ask a fluent speaker to review important learner-facing copy.
  • Check that no value was accidentally left empty: an empty string restores the built-in English text.
  • Copy only the JSON object, without any surrounding explanation or code fences.

Embedin checks the JSON structure and required placeholders, but it does not judge translation quality. If validation reports an error, fix the draft yourself or ask the AI assistant to correct it while preserving the other keys and values.

4. Keep placeholders intact

Some messages contain placeholders that Embedin replaces with real information:

  • {date} inserts a cohort start or lesson release date.
  • {score} inserts a learner's quiz score.
  • {passingScore} inserts the score needed to pass.
  • {domain} identifies the website in a domain-related message.

Translate the surrounding sentence, but preserve each required placeholder exactly. You can move a placeholder within the sentence to suit the language.

For example:

{
  "quizFailedMessage": "Tu resultado fue {score}%. Necesitas {passingScore}% para aprobar."
}

Do not replace {date} with a particular calendar date or rename it to a translated word. The same message needs to work with the actual date for each cohort or lesson.

The importer checks required placeholders. An empty string is the exception: it restores the built-in text rather than supplying a custom message.

5. Paste and apply your JSON

Return to Import JSON, paste your object into Translation JSON, and select Apply translations.

When the input is valid:

  1. The included values populate their matching form fields.
  2. Fields you omitted keep their current values, including other edits in the form.
  3. The existing autosave flow saves the changes.

Wait for the Saved confirmation. If saving fails, your values remain in the form and you can select Retry saving.

You do not need to import the whole template. A small update is often easier to review:

{
  "ctaTitle": "Ready to begin?",
  "ctaMessageLoggedOut": "Sign in or enroll to start learning with us."
}

That object updates only those two messages. It leaves cohort labels, quiz messages, and other translations unchanged.

6. Fix validation errors without losing existing text

If the importer finds a problem, it shows No translations were imported and explains what needs fixing. It does not apply the valid entries from an otherwise invalid import.

Check these common causes:

  • Invalid JSON: Use double quotes, remove comments and trailing commas, and paste only the JSON object without Markdown code fences.
  • Wrong structure: Paste a flat object, not an array or an object wrapped inside a translations property.
  • Unsupported key: Use a key listed in the page's JSON template.
  • Non-text value: Values must be strings, not numbers, booleans, objects, or null.
  • Missing placeholder: Keep every required token, such as both {score} and {passingScore} in the quiz failure message.

Correct the text and select Apply translations again. Pasting or editing JSON alone does not update the translation fields.

7. Preview the learner experience

After saving, select Preview at the top of the page and review the screens you changed.

For a cohort course, check the welcome screen before the cohort starts, the schedule labels, and the release messages in the outline. If you changed the community invitation, remember that While you wait appears only when community is enabled.

Also check longer translations on a narrow screen. A short English button label can become a much longer phrase in another language.

For more on the community itself, see how to enable community for your course.

Restore the built-in text when needed

To reset one field, select its Use built-in action on the translations page. You can also import an empty string:

{
  "cohortWelcomeTitle": ""
}

This restores the built-in English welcome title without resetting your other translations.

Cancel closes the import panel and discards the pasted draft. It does not undo values you have already applied to the form.

A simple translation workflow

Start with a small set of labels, use AI or a translator to draft the values, and review the wording while keeping keys and placeholders unchanged. Apply the JSON and preview the result. Once the wording feels right, repeat the process for the next section.

You can reuse the same JSON for another course by importing it on that course's translations page. Review it first, especially if the courses use different terminology.

Ready to put your course on your own site? Follow the guide to embedding an online course on your website, then use translations to make the learner experience feel at home there.

Published

More guides