This feature is available from the Pro plan and above.
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.
Preparations
Before getting started, check out our detailed tutorial on setting up Lokalise with Storyblok for step-by-step guidance.
Adding languages in Storyblok
First, add the languages you want to translate into. Open your Storyblok dashboard, navigate to Settings > Internationalization, and configure your default and additional languages.
Storyblok recommends using hyphens for regional codes (pt-br instead of pt_br). You can choose any format, but it's important to stay consistent. Lokalise, however, uses underscores, so if you stick with hyphens, you’ll need to adjust the language settings in Lokalise later.
Once your language settings are configured, click Save.
Setting translatable fields
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 Lokalise project
Create a Marketing and support Lokalise project if you haven’t already.
Enter a project name, select your base and target languages, and choose Webflow from the Content integrations dropdown.
Once everything is set, click Create project to finalize. You're now ready to start translating your Storyblok content.
Setting up the app
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.
Getting Storyblok personal access token
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.
Finalizing app configuration
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.
Importing content from Storyblok to Lokalise
The Storyblok app supports automated content imports, making the process easier. For more details, check out the Automated import/export article.
Loading content
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.
Selecting items for translation
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.
Adjusting import options
Choose the languages to import. If your content is only in English, remove other languages from the list to avoid importing empty translations.
Overwrite updated translations: Enable this if you want to update existing Lokalise translations with the latest versions from Storyblok.
Skip key creation for empty translations: Prevents Lokalise from creating empty translation keys for untranslated fields.
Automations: If enabled in your Lokalise project, apply automated rules to the imported content.
Assign tags: Add one or more tags to imported keys.
Note that tags will be reset on subsequent re-imports. Learn more in the Special notes section.
Once everything is set, click OK. The content will be imported in the background, and a notification will appear when it's done.
Importing references
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.
Adjusting languages with regional codes (optional)
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.
Managing translations
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.
Exporting content from Lokalise to Storyblok
This app supports automated exports. For more details, check out the Automated import/export article.
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.
Checking the result
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.
Special notes
Key tags and content importing
Lokalise keys can have different tags assigned at various stages:
During import: The Storyblok app automatically assigns specific tags, such as a default Storyblok tag.
Before import: You can add custom tags by adjusting the Tags option.
After import: Tags can be modified or added manually in the Lokalise UI.
However, during a re-import from Storyblok to Lokalise, tags behave differently:
Automatically assigned tags are always retained.
Tags set before import are reset.
Tags added via Lokalise remain unchanged.
Blocks inside RichText fields
Lokalise fully supports blocks within RichText fields and ensures proper synchronization with Storyblok. However, there are some key considerations.
Content on Lokalise
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:
<p>Regular paragraph within RichText</p>
<blok id="567-def-abc">
<blok-component uid="123-abc" component="Article block">
<blok-field name="ArticleBody" type="doc">
<p>Article Body inside RichText</p>
</blok-field>
<blok-field name="ArticleTitle">
Article title inside RichText
</blok-field>
<blok-field name="PublicationDate">
2024-04-28 10:18
</blok-field>
</blok-component>
</blok>
In this structure:
Standard paragraphs use basic
<p>
tags.Blocks are enclosed within
<blok>
tags.Each block component contains individual
<blok-field>
elements.
For Marketing and support projects, blocks inside RichText fields are separated into unique translation keys for easier management.
Translatable attribute
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 representable as strings
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.