Storyblok is a headless content management system (CMS) that helps you manage and deliver content flexibly across multiple platforms. This guide will show you how to integrate Storyblok with Lokalise, making your translation and localization processes simpler and more streamlined.

First, you need to add your desired content languages in Storyblok. To do this, go to your Storyblok dashboard and navigate to Settings > Internationalization.

Here, you can set the default language for your content and add any additional languages you want to translate into.

For example, you might set English as the default locale, with German and Spanish as additional languages. Note that Storyblok doesn’t support language codes with dashes (e.g., use de_de instead of de-de).

Once your language settings are adjusted, hit Save.

Next, ensure that the fields in your content schema are marked as translatable. To do this, go to the Block Library and click on the block you want to make translatable.

Select the specific field.

Check the Translatable option and save your changes.

After setting the necessary fields as translatable, you’re ready to continue in 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 see the installation dialog pop up:

Enter your personal access token and select your region.

To get your personal access token:

Go back to Lokalise, paste your token into the text box, and click Authorize. Make sure to keep your personal token secure and avoid sharing it publicly.

Next, you’ll see a new dialog for app configuration.

Select your Storyblok space and set the base language of your content. Once you’ve filled out the settings, click Save.

That’s it! Your Storyblok app is now connected to Lokalise.

When you connect the app, your Storyblok data will be loaded automatically. If you don’t see the items right away, click Reload list to refresh.

If you need to update the imported content, just click the Refresh button. Once the refresh is complete, a notification will confirm the update.

To start translating your content, first select the items you want to import. Browse through your list of content items and check the boxes next to the ones you want to translate.

You can also use the Search box or set up a custom filter using the Filter dropdown.

When you’re ready, click Import selected.

Next, pick the languages you want to import. For example, if your content is only in English right now, you can remove other languages from the import list, as their translations are currently empty.

When everything is set, click OK. Your content will be imported to Lokalise in the background, and a notification will let you know when it’s finished.

Sometimes, you may encounter the error message Field is a reference.

This means the item doesn’t have any translatable content on its own, but it references other fields. To include these, select the Import references option, which will pull in all records linked to that field.

To start translating, head back to the project editor by clicking on your project name in the top left corner. Here, you’ll see all the content you’ve imported from Storyblok.

From this point, you can manage your translations just like you would with any other content in Lokalise. Adjust texts, add translations, and review them until everything’s good to go.

After translating your content, the next step is to export it back to Storyblok.

Lokalise will handle the export in the background, and you’ll receive a notification once the process is complete.

Now, head back to Storyblok to see your translated content in action! For example, if you translated content into Spanish, you should see it reflected in the Spanish version of your project.

To switch between languages, use the language dropdown in the top menu.

And that’s it! You can now repeat this process to translate more Storyblok content effortlessly. As you can see, integrating Storyblok with Lokalise is straightforward, making it easier to manage and localize your content across multiple languages.

Your Lokalise keys can be assigned various tags. These tags can be added at different stages:

However, it’s important to note how these tags behave during a re-import from Storyblok to Lokalise:

Lokalise fully supports blocks within RichText fields and ensures they sync correctly with Storyblok. However, here are some important details to keep in mind:

If your Storyblok content includes blocks inside RichText fields, they will be grouped under a single key in Lokalise. The content is formatted using custom HTML tags to represent different elements.

Example:

In the example above, standard paragraphs are displayed using a basic <p> tag, while blocks are grouped under a custom <blok> tag. Each individual block element appears within <blok-field> tags.

For Marketing and support projects, blocks inside RichText fields are separated into unique translation keys for easier management.

Due to technical limitations, Lokalise may not detect which specific fields within a RichText block are marked as non-translatable in Storyblok. As a result, all fields are imported into Lokalise regardless of their translatable status.

These fields can still be safely exported back to Storyblok without any issues.

Fields such as DateTime, Number, Image (Old), and File (Old) are processed as regular text fields in Lokalise. Double-check that the localized formats match the original formats in Storyblok. If the formats differ (e.g., date and time formatting), the affected fields might not display correctly and could end up being empty upon export.