Translate JSON with DeepL

by Denis Augsburger

With Simpleen you can selectively translate your JSON data including a variety of subformats.

Since the DeepL API supports XML and text formats, we developed Simpleen to add the possibility of handling additional formats like HTML, Markdown and JSON. In this article, we are going to share some insights about the translation of JSON data with DeepL and Simpleen.

For example, let's take the following recipe in this post:

   "title": "World's Best Lasagna",
   "instructions": [
     "Heat up the oven", 
     "Cut the onions", 
     "Cook the ground beef, onions, and garlic over medium heat until well browned"
   "notes": "<p class=\"info\">One of my most favorite foods</p>",
   "ingredients": [{
     "amount": "2 pcs",
     "name": "onions"
   }, {
     "amount": "1 tbsp",
     "name": "salt"
   "published": "2020-07-19",
   "author": "Denis"

When translating this kind of data, we may only want to translate parts of the provided recipe.

Keep your structure

To do this, we want to keep our existing structure as well as not corrupt any data in it. Also, our styles and data structure in HTML need to stay intact.

Keys should not be translated otherwise your code doesn't work anymore. Some values should stay as is, i.e. the amount of the ingredient, because it is handled by a special conversion function. The same applies to the published date which is handled by localization afterwards.

Also, some of the included formats like HTML or Markdown should be translated without losing their formatting. Simpleen makes it easy to selectively translate some content in your JSON structure. Just define your selections and formats in your Simpleen translator.

Keep your context

Especially with machine translation services like DeepL it is important to translate the text within the context. With regards to our recipe example, the entire JSON structure depends on each other and represents one recipe. As a result, translations are better when embedded in the context. To ensure that DeepL receives the necessary context, Simpleen provides DeepL with all of your selected text that you want to translate, not just junks of it.

Note: That’s why we cannot recommend the translation of single words or a single sentence. You achieve much better results with multiple sentences.

More formats per JSON selection

With JSON you can selectively translate your structure with multiple formats. The format of each selection (field) can be configured individually. Currently available formats are:

  • HTML
  • Markdown
  • Text
  • XML

Implement the recipe example

So let’s see how this works with the example from above and translate our recipe into Japanese.

First: Create a Simpleen Account and configure your DeepL API-Key in the settings.

Then create your Translator. Your selections for the example above could be as follows:











Your created translators can be used independently with their ID. They are configured with your expected format, selections, languages as well as a glossary.

Then you can use your translator to translate (some of) your JSON data.

/* Post-Request to use your translator for translations */"{ID}/translate", {
  // You can select which part of the JSON should be translated via selections
  text: JSON.stringify(recipe),
options: {
  headers: {
    'Authentication': 'Bearer {YOUR_BEARER_TOKEN}'

Our result with a configured target language of Japanese looks like this:

    "title": "世界一おいしいラザニア",
    "instructions": [
    "notes": "<p class=\"info\">一番好きな食べ物の一つ</p>",
    "ingredients": [
            "amount": "2 pcs",
            "name": "玉ねぎ"
            "amount": "1 tbspn",
            "name": "塩"
    "published": "2020-07-19",
    "author": "Denis"


You can additionally use common placeholders from different i18n libraries. These are not translated and can be used later on to match with the provided values. For example the sentence: "There are {{count}} similar recipes" becomes to "似た {{count}} ようなレシピがあります。".

For further information check out Simpleen, the Simpleen API-documentation or get in touch with us for questions or feedback:

Denis is a passionate software engineer with many years of experience in web development. He's specialized in programming with React, GraphQL, GatsbyJS and TypeScript. In his articles he writes about working with these technologies and enjoys to share opportunities and challenges with the community.