Storyblok is a headless content management system that allows users to manage multi-purpose content. In this document you will learn how to integrate Storyblok with Lokalise.

First of all, you will need to add the desired content languages on Storyblok. To achieve that, open your Storyblok board and proceed to Settings > Internationalization:

Here you can set a default language of your content and add other languages that you would like to translate into:

In the example above, we have English set as the default locale along with two additional languages: German and Spanish. Please note that due to Storyblok limitations language codes shouldn't include dashes - (for example you should use code de_de instead of de-de).

Once you have adjusted language settings and hit Save.

Also make sure to mark all the necessary schema fields as translatable. To achieve that, proceed to the Block Library and click on the item that you wish to make translatable:

Click on the field:

Tick the Translatable option and save the changes:

Now you can return to Lokalise!

Open your Lokalise project and click Apps in the main menu:

Find the Storyblok app, click on it, and then press Install. You'll be presented with the following dialog:

You'll have to enter your personal access token and choose the region.

To obtain a personal access token, return to Storyblok, click on your account in the bottom left corner, and then choose Account settings.

Find the Personal access tokens section and hit Generate new token:

Copy your new token, return to Lokalise, paste it into the corresponding text box, and click Authorize. Please note that your personal token must be kept secure and should not be publicly exposed!

You will be presented with another dialog to configure the app:

Here choose your Storyblok space and the base language of your content. Once you are ready, hit Save.

Your Storyblok data will be loaded automatically (you might need to click Reload list to see all the items).

If you need to refresh the loaded data, click on the corresponding button:

After the refresh process is completed, you’ll see a notification message.

To start translating your content on Lokalise, you’ll need to import the desired items first. To achieve that, find the items you want to translate and put checkmarks next to them:

You can also use the search box in the top right corner or construct a new filter using the Filter dropdown. Once you are ready, click Import selected.

Choose the content languages that you would like to import:

For example, if your content is currently available only in English, then you can remove all other languages from the Import languages list as the corresponding translations are empty anyways.

If you have already imported the chosen items once and wish to download newer versions of the same items, then tick the Overwrite updated translations checkbox. Please note that this will overwrite all the corresponding translations in your Lokalise project with new versions from Storyblok.

if you do not want to create translation keys for content that is empty on Storyblok, you can tick the Skip key creation for empty translations option.

If your current project has automations enabled, you'll be able to Automations options to apply your rules to the imported content.

You may also need to enable the Import references option. What does that mean? If you get an issue Field is a reference:

it simply means that this item will not be imported on its own as it does not contain any translatable content. However, if you select this item and enable the Import references option then all records referenced from this field will get imported automatically.

Finally, you can assign one or more tags to the imported translation keys by adjusting the corresponding field.

Click OK. Your content will be imported to Lokalise in the background. After this process is finished, you’ll see a notification message.

Now return to the project editor by clicking on the project name in the top left corner. You will see all the imported content:

At this point you can perform translations as usual.

Once you have translated the content, you’ll need to export it back to Storyblok. To achieve that, proceed to the Apps page again and open the Storyblok app.

Find the items that you wish to export, tick the checkboxes next to them, and click Export selected:

Choose the languages that you would like to export:

If needed, uncheck the Don’t export empty translations option. Once you are ready, click OK. Once the process is finished, you’ll see a notification message.

At this point you can return to Storyblok and check the result! Here's an example with Spanish translation:

To change the content language, use the dropdown at the top menu:

And this is it! You can repeat the whole process again to translate more Storyblok content with ease. As you can see, there is nothing complex about integrating Storyblok with Lokalise, and this app enables you to manage localized content much easily!

Lokalise supports the inclusion of blocks within RichText fields and ensures they synchronize correctly. Here are important details to know.

When using the Storyblok app for Web and mobile projects in Lokalise, and if the data from Storyblok includes blocks in RichText fields, these blocks will appear under a single key. The content is organized into different custom HTML tags.

Example:

In this example, regular paragraphs are shown with a basic <p> tag, while other blocks are grouped under the custom <blok> tag. Each element within these blocks is shown as a <blok-field>.

For Marketing and support projects, blocks in RichText fields are shown as separate translation keys.

Lokalise may not retrieve detailed information about blocks within RichText fields due to technical constraints. Even if some fields are marked as non-translatable, Lokalise will still import them.

These non-translatable fields can be safely imported back to Storyblok.

When dealing with fields whose values are not inherently strings, such as DateTime, Number, Image (Old), and File (Old), careful handling is necessary. These fields are processed as regular text fields in Lokalise due to technical constraints. It’s important to ensure that any localized values, such as date and time formats, are consistent with those used in Storyblok. If the formats are mismatched, the exported fields might be empty.