How to export and import a translatable version of my story?

To export or import translatable versions of your story, you need to use the Storyblok Management API (opens in a new window). Your block and field must have the “translatable” option enabled for the import to work.

Export Stories as XML

To export a story, you need your story ID and the ID of the space you want to export stories from. Then, you can make a GET request. Also, make sure you add Authorization to the header with your personal 0auth access token (opens in a new window) as the value.

Resource	Information
Endpoint	`https://mapi.storyblok.com/v1/spaces/:space_id/stories/:story_id/export.xml?lang_code=language_code&export_lang=true`
Method	`GET`
Header	`Authorization:YOUR_0AUTH_TOKEN`

Example Request

GET https://mapi.storyblok.com/v1/spaces/:space_id/stories/:story_id/export.xml?lang_code=language_code&export_lang=true

Example Request

import StoryblokClient from "storyblok-js-client";

const Storyblok = new StoryblokClient({
    oauthToken: "YOUR_OAUTH_TOKEN",
});

const spaceId = 134445;
const storyId = 86930141;
const langCode = "language_code";

const exportStoriesXml = async () => {
    try {
        const response = await Storyblok.get(`spaces/${spaceId}/stories/${storyId}/export.xml?lang_code=${langCode}&export_lang=true`);
        console.log(response.data);
    } catch (error) {
        console.error("Error:", error);
    }
};

exportStoriesXml();

Export Stories as JSON

Resource	Information
Endpoint	`https://mapi.storyblok.com/v1/spaces/:space_id/stories/:story_id/export.json?lang_code=language_code&export_lang=true`
Method	`GET`
Header	`Authorization: YOUR_OAUTH_TOKEN`

Example Request

GET https://mapi.storyblok.com/v1/spaces/:space_id/stories/:story_id/export.json?lang_code=language_code&export_lang=true

Example Request

import StoryblokClient from "storyblok-js-client";

const Storyblok = new StoryblokClient({
    oauthToken: "YOUR_OAUTH_TOKEN",
});

const spaceId = 134445;
const storyId = 86930141;
const langCode = "language_code";

const exportStories = async () => {
    try {
        const response = await Storyblok.get(`spaces/${spaceId}/stories/${storyId}/export.json?lang_code=${langCode}&export_lang=true`);
        console.log(response.data);
    } catch (error) {
        console.error("Error:", error);
    }
};

exportStories();

hint:

You can find your 0Auth token in your Storyblok user account dashboard. You can also see our documentation for language code.

Importing Stories

You can either import stories as XML or JSON. To do this, just like when exporting stories, you need your story ID and the ID of the space, you want to import the story into. Since you’ll be updating your space, you need to make a PUT request and add Authorization to the header with your personal 0auth access token (opens in a new window) as the value. The body of the request should then contain the story you want to import in this format {"data": YOUR_STRINGIFIED_IMPORT_STORY}. It's important to note that imported stories can only be in JSON or XML format.

NOTE:

The data you’re importing must be a string. Whether it’s in XML or JSON format.

Import Stories as XML

Resource	Information
Endpoint	`https://mapi.storyblok.com/v1/spaces/:space_id/stories/:story_id/import.xml`
Method	`PUT`
Header	`Authorization: YOUR_OAUTH_TOKEN`
Body	`{"data": YOUR_STRINGIFIED_IMPORT_XML"}`

Example Request

import StoryblokClient from "storyblok-js-client";

const Storyblok = new StoryblokClient({
    oauthToken: "YOUR_OAUTH_TOKEN",
});

const spaceId = 134445;
const storyId = 86930141;

const xml = `<?xml version="1.0" encoding="UTF-8"?>
<page text_nodes="0" filename="building-a-food-store" url="posts/building-a-food-store" id="86930141" language="default">
  <name>Building a phone store</name>
  <tags>
    <tag id="69c9f9dd-b5e5-4859-a5ee-0bf8a1319c8e:Post:image" type="STRING">
      <text>
        <![CDATA[//a.storyblok.com/f/134445/1500x844/19eeaff370/eeacbea1-99a3-4a96-8ee9-980ae5f9dfe6.jpeg]]>
      </text>
    </tag>
    <tag id="69c9f9dd-b5e5-4859-a5ee-0bf8a1319c8e:Post:intro" type="STRING">
      <text>
        <![CDATA[phone stores are important for mankind]]>
      </text>
    </tag>
    <tag id="69c9f9dd-b5e5-4859-a5ee-0bf8a1319c8e:Post:title" type="STRING">
      <text>
        <![CDATA[Building a phone store]]>
      </text>
    </tag>
    <tag id="69c9f9dd-b5e5-4859-a5ee-0bf8a1319c8e:Post:author" type="STRING">
      <text>
        <![CDATA[cd9f7534-b437-4d3f-b23d-022f464f4cf3]]>
      </text>
    </tag>
    <tag id="69c9f9dd-b5e5-4859-a5ee-0bf8a1319c8e:Post:richtext:long_text" type="STRING">
      <text>
        <![CDATA[{"type":"doc","content":[{"type":"paragraph","content":[{"text":"this is a phone store ","type":"text"}]}]}]]>
      </text>
    </tag>
  </tags>
</page>`;

const importXmlStory = async () => {
    try {
        const response = await Storyblok.put(`spaces/${spaceId}/stories/${storyId}/import.xml`, {
            data: xml
        });

        console.log(response.data);
    } catch (error) {
        console.error("Error:", error);
    }
};

importXmlStory();

Import Stories as JSON

Resource	Information
Endpoint	`https://mapi.storyblok.com/v1/spaces/:space_id/stories/:story_id/import.json`
Method	`PUT`
Header	`Authorization:YOUR_MANAGEMENT_TOKEN`
Body	`{"data": YOUR_STRINGIFIED_IMPORT_JSON}`

Example request

import StoryblokClient from "storyblok-js-client";

const Storyblok = new StoryblokClient({
    oauthToken: "YOUR_OAUTH_TOKEN",
});

const spaceId = 134445;
const pageId = 86930141;
const authToken = "YOUR_OAUTH_TOKEN";

const json = {
    "69c9f9dd-b5e5-4859-a5ee-0bf8a1319c8e:Post:author": "cd9f7534-b437-4d3f-b23d-022f464f4cf3",
    "69c9f9dd-b5e5-4859-a5ee-0bf8a1319c8e:Post:image": "//a.storyblok.com/f/134445/1500x844/19eeaff370/eeacbea1-99a3-4a96-8ee9-980ae5f9dfe6.jpeg",
    "69c9f9dd-b5e5-4859-a5ee-0bf8a1319c8e:Post:intro": "iphone stores are important for mankind",
    "69c9f9dd-b5e5-4859-a5ee-0bf8a1319c8e:Post:richtext:long_text": '{"type":"doc","content":[{"type":"paragraph","content":[{"text":"this is an iPhone store ","type":"text"}]}]}',
    "69c9f9dd-b5e5-4859-a5ee-0bf8a1319c8e:Post:title": "Building an iPhone store",
    language: "default",
    page: `${pageId}`,
    text_nodes: 0,
    url: "posts/building-an-iphone-store",
};

const importStory = async () => {
    try {
        const response = await Storyblok.put(`spaces/${spaceId}/stories/${pageId}/import.json`, {
            data: JSON.stringify(json),
        });

        console.log(response.data);
    } catch (error) {
        console.error("Error:", error);
    }
};

importStory();

HINT:

An easy way to check if the story update has worked is to access the same story in the Visual Editor and reload the page.

Parameters for the specific language

To export/import your story in specific languages already added to your space, add the optional param ?lang_code=language_code to the endpoint.

NOTE:

You can easily import and export translatable fields of your stories using the import translatable fields and export translatable fields apps respectively. The app is available in the Business plan or superior.

Request with `version=2`

In version one, the page:richtext response was stringified, requiring JSON.parse for processing. In version two, it is exported directly as a text value. This version also preserves the structure of blocks within rich text, including nested blocks, making it especially useful for translation scenarios.

Resource	Information
Endpoint	`https://mapi.storyblok.com/v1/spaces/:space_id/stories/:story_id/export.json?lang_code=language_code&export_lang=true?version=2`
Method	`GET`
Header	`Authorization: YOUR_OAUTH_TOKEN`

Response Example with version=2 Query Parameter

{
  '59ea90a7-c548-4d96-ae11-3d4ed40a5176:dp_richtext:richtext:content/content[0].content[0].text':
    'Dummy text content',
  '59ea90a7-c548-4d96-ae11-3d4ed40a5176:dp_richtext:richtext:content/content[1].attrs.body[0].content.content[0].content[0].text':
    'This is a hint component',
  'i-19d10cb3-3884-45bf-a1c4-5f27e852d636:dp_hint:color': 'green',
  'i-19d10cb3-3884-45bf-a1c4-5f27e852d636:dp_hint:richtext:content/content[0].content[0].text':
    'This is a hint component',
  '6fae1c25-6c32-4268-8d52-173e8ca4996a:dp_page:og_title': '',
  page: '592234781',
  language: 'default',
  url: 'docs/plugins/tool-plugins',
  text_nodes: 0,
}

Import Stories as JSON

Resource	Information
Endpoint	`https://mapi.storyblok.com/v1/spaces/:space_id/stories/:story_id/import.json?version=2`
Method	`PUT`
Header	`Authorization:YOUR_MANAGEMENT_TOKEN`
Body	`{"data": YOUR_V2_IMPORT_DATA}`

Example request

import StoryblokClient from "storyblok-js-client";

const Storyblok = new StoryblokClient({
    oauthToken: "YOUR_OAUTH_TOKEN",
});

const spaceId = 134445;
const pageId = 86930141;
const authToken = "YOUR_OAUTH_TOKEN";

const v2Data = {
  '59ea90a7-c548-4d96-ae11-3d4ed40a5176:dp_richtext:richtext:content/content[0].content[0].text':
    'Dummy text content',
  '59ea90a7-c548-4d96-ae11-3d4ed40a5176:dp_richtext:richtext:content/content[1].attrs.body[0].content.content[0].content[0].text':
    'This is a hint component',
  'i-19d10cb3-3884-45bf-a1c4-5f27e852d636:dp_hint:color': 'green',
  'i-19d10cb3-3884-45bf-a1c4-5f27e852d636:dp_hint:richtext:content/content[0].content[0].text':
    'This is a hint component',
  '6fae1c25-6c32-4268-8d52-173e8ca4996a:dp_page:og_title': '',
  page: `${pageId}`,
  language: 'default',
  url: 'docs/plugins/tool-plugins',
  text_nodes: 0,
};

const importStory = async () => {
    try {
        const response = await Storyblok.put(`spaces/${spaceId}/stories/${pageId}/import.json`, {
            data: v2Data,
        });

        console.log(response.data);
    } catch (error) {
        console.error("Error:", error);
    }
};

importStory();

How to export and import a translatable version of my story?

Export Stories as XML

Export Stories as JSON

Importing Stories

Import Stories as XML

Import Stories as JSON

Parameters for the specific language

Request with version=2

Import Stories as JSON

Request with `version=2`