Storyblok is a headless content management system (CMS) that allows flexible content management and delivery across multiple platforms. This guide will walk you through integrating Storyblok with Lokalise to simplify your translation and localization workflows.

First, add the languages you want to translate into. Open your Storyblok dashboard, navigate to Settings > Internationalization, and configure your default and additional languages.

Once your language settings are configured, click Save.

Ensure that the fields in your content schema are marked as translatable. Open the Block Library and select the block you want to make translatable:

Choose the specific field:

Check Translatable, and save your changes.

Once you've marked the necessary fields, you're ready to continue in Lokalise.

Create a Marketing and support Lokalise project if you haven’t already.

Enter a project name, select your base and target languages, and choose Storyblok from the Content integrations dropdown.

Once everything is set, click Create project to finalize. You're now ready to start translating your Storyblok content.

Open your Lokalise project and click Content management in the top menu.

Click Install, and the installation dialog will appear.

Enter your personal access token and select your region.

To obtain your personal access token, open Storyblok, click on your account in the bottom left corner, and select Account settings.

Proceed to the Personal access tokens section:

Click Generate new token at the bottom of the page.

Assign a name, set an expiration date, and click Generate & Copy token.

Copy the token immediately, as it won’t be visible later. Keep it secure and avoid sharing it publicly.

Return to Lokalise, paste your token into the Personal access token field, and click Authorize. A configuration dialog will appear.

Select your Storyblok space and set the base language for your content. Once all settings are filled in, click Save.

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

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

To update imported content, click Refresh. Once the process is complete, a notification will confirm the update.

To begin translating, select the items you want to import by checking the boxes next to them.

Use the Search box or set up a custom filter using the Filter dropdown if needed.

When ready, click Import selected.

Choose the languages to import. If your content is only in English, remove other languages from the list to avoid importing empty translations.

Once everything is set, click OK. The content will be imported in the background, and a notification will appear when it's done.

If you see the error Field is a reference, it means the item doesn’t contain translatable content but references other fields.

To include these, enable Import references, which will pull in all linked records.

If you use languages with regional codes and opted for hyphens in Storyblok (pt-br instead of pt_br), update the locales in Lokalise.

Go to the Editor, open the languages dropdown, find the relevant language, and open the language menu.

Select Settings:

Turn on Custom language code, and enter the hyphenated code.

Click Save to apply the changes.

To start translating, go to the project editor by clicking on your project name in the top left corner. Here, you'll find all the content imported from Storyblok.

You can now manage translations as usual in Lokalise. Adjust texts, add translations, and review them until everything is ready.

Once translations are complete, export them back to Storyblok. Open the Content management tab, select the items you want to export, and click Export selected.

In the dialog box, choose the languages to export.

If you want to include empty translations, uncheck Don’t export empty translations.

When everything is set, click OK. Lokalise will process the export in the background, and you'll receive a notification once it's finished.

Go to Storyblok to see your translated content in action. Use the language dropdown in the top menu to switch between languages.

That’s it! You can now repeat this process for more Storyblok content. Integrating Storyblok with Lokalise makes managing and localizing content simple and efficient.

Lokalise keys can have different tags assigned at various stages:

However, during a re-import from Storyblok to Lokalise, tags behave differently:

Lokalise fully supports blocks within RichText fields and ensures proper synchronization with Storyblok. However, there are some key considerations.

If 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 this structure:

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 inside a RichText block are marked as non-translatable in Storyblok. As a result, all fields are imported into Lokalise, regardless of their translatable status. However, 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. Ensure that localized formats match the original formats in Storyblok. If there are differences (e.g., date and time formatting), these fields may not display correctly and could appear empty upon export.