Managing websites in multiple languages can be very challenging. While some content management systems are built with internationalization in mind and do the job well (including Storyblok!), nothing compares to a fully-featured localization platform designed to produce and maintain translations of your content in dozens of languages from the very start. Integrating your content seamlessly with such a platform allows you to roll out new languages rapidly and without any hassle.
Learn more about the Best Multilingual Content Management Systems
Building upon the experience we gained after our Strapi localization plugin made its splash in the Strapi community, we are ready to offer our help to everyone struggling to get their Storyblok content translated with our new localization solution.
☝️ What is Storyblok? 🔗
Storyblok is an enterprise-level "headless" content management system for companies, agencies, and organizations with prolific content needs. It features template layouts, custom modules, pre-built components, video integration, and more.
Storyblok also has a user-friendly interface that makes it simple for users to manage their content in any format without knowing how to code. In fact, it is probably the only headless CMS that features a real-time visual editor.
Storyblok offers multilingual content and integrates with various translation management platforms, Localazy included. These integrations let you make your content available to a global audience.
How does the Localazy integration work?
Storyblok offers a couple of ways of creating Extensions. To deliver the smoothest experience, we decided to create the complete Custom Application. Unfortunately, Storyblok does not yet offer a way to easily install Custom Applications for other users (e.g., via Marketplace).
That's why we at Localazy decided to host the integration ourselves and made it available via the Localazy Console. It's a convenient way of providing 3rd party integrations quickly that cannot be delivered directly to the target platform while keeping the Localazy UI clean.
The integration's purpose is to provide a way of transferring content between Storyblok and Localazy seamlessly. That way, you'll be able to manage your content in many languages easily.
📼 Watch video 🔗
You can also watch a video demonstration of the Storyblok Integration before you dive into the rest of this article.
🥂 Connect Storyblok & Localazy 🔗
First, create a Localazy account. After logging in, create a new project by clicking on Start a new localization project and filling in the information, such as project name, etc. Do not forget to set the Source language to respect your Storyblok space Default language choice.
🏁 To learn more about using Localazy, read the Getting Started Guide
The project is currently empty, but we'll populate it with data from our Storyblok website soon. Choose the Storyblok integration from the list and follow the instructions.
Then, go to Localazy Console. The best way to navigate there is to go to the Project Settings and click the Dev Console Tab. Then, select Integrations in the left menu and find your project. Click on the link icon and choose Storyblok Integration.
After selecting the integration, you'll be asked to provide your Storyblok Space ID and API Token. We need these to connect the Localazy project to your Storyblok Space and access the stories and components.
Learn how to obtain Space ID and API token.
After filling in the required fields, click Connect.
Note: Your data is encrypted and used only for communication with the Storyblok API.
After connecting, two new icons should appear. Click on any of the new "cloud" icons. A new modal window will appear. All the Localazy ↔️ Storyblok communication is managed from this place.
You can also remove the connection of the integration by clicking on the "trash" icon.
Overview Tab 🔗
In the modal window, there are four tabs that allow you to manage various aspects of the integration and perform the upload and download actions.
There's various information displayed in the Overview Tab. But, most importantly, there are two things. The first thing you should pay attention to is the Remaining organization keys count. If you run out of the keys, you won't be able to upload new translations back to Storyblok. To resolve this, you must upgrade your plan to one with a higher source key limit in the Marketplace.
💳 Learn more about Localazy Pricing options
The second important thing is the languages table. Because Storyblok Management API does not provide any way to add a new or update an existing language automatically, you have to keep languages in Storyblok and Localazy in sync manually. That's why this comparison table comes in handy. You can see all the Space languages and connected Localazy project languages, and always double-check whether everything is up-to-date and synchronized correctly.
Also, always check whether the language codes are consistent in Localazy and Storyblok to avoid any accidents caused by discrepancies between Storyblok and Localazy.
Settings Tab 🔗
There are also a couple of settings available to adjust the Storyblok integration according to your workflow. Let's go through each of the options with an explanation.
Sync translatable fields with export: What does it mean? How to use it?
When you initiate the download action, every story is exported and downloaded to Localazy. The way that Storyblok works is that it exports all the text-based fields and, unfortunately, disregards the component's Translatable setup. That means that even though your component's Translatable setup is correct, all text-based fields will still be uploaded to Localazy.
This is unfortunate when your components contain some text-based internal metadata or styling attributes.
The solution to this problem would be to go through each component's setups and check the Exclude from export checkbox for every field that is not marked as Translatable. This would obviously be a tedious, painful & error-prone manual procedure.
With the Sync translatable fields with export? option checked, a synchronization before every Download to Localazy happens. This will ensure that all your untranslatable fields are excluded from the story export. And vice-versa, it ensures that every translatable field is included in the story export.
Download existing localized entries?
If this option is checked, every download to Localazy will also transfer the existing localizations to Localazy, not just the one in the Default language. Note that it's important to follow ISO 639 while defining a language code in Storyblok.
In most cases, you'd like to use it with the Set Storyblok as Souce of Truth option.
Set Storyblok as Souce of Truth
If this option is active, downloading to Localazy will set all downloaded translations as the current version. By default, Localazy doesn't overwrite existing current versions for translations and lets you decide through the review process. This option can be handy when you want to quickly edit a translation in the Storyblok administration without looking it up in Localazy.
🚩 Translate Storyblok content 🔗
Now that you have decided how to configure the integration settings and understand the functions a little better, we can dive into the translation process. First, we need to download the content from Storyblok to Localazy, but before we do, let's answer a couple of questions...
I have already translated some content. Can I sync it with Localazy?
Yes, the Localazy integration allows you to download your translated content in languages other than the Default language. To do so, go to the Settings Tab and check the Download existing localized entries? option.
How does Localazy handle the Storyblok RichText field?
It's a well-known fact that Storyblok interprets Rich Text fields as JSON. That basically means that if you'd upload such a structure to any Translation Management System, it would be hard to translate as a user would see a JSON structure to be translated.
Thankfully, Localazy provides a way to overcome such issues by 1:1 converting the JSON to HTML during the download. This way, the field content is user-friendly and can be translated easily.
During the upload back to Storyblok, Localazy handles the conversion as well - HTML content is 1:1 converted back to the Storyblok Rich Text JSON structure.
How does Localazy handle the Storyblok Table field?
Table fields are already well-handled by Storyblok export/import endpoints Localazy uses. Every cell of a table is exported as a separate key.
During the import, Storyblok handles the whole process.
Download your content to Localazy 🔗
Now you are ready to download the content to Localazy, go to the Download to Localazy tab and click the Download All Stories To Localazy button.
Go to your project in Localazy, and you'll see the downloaded source language and possibly your other languages (depending on your setup). Let's start translating!
Translate in Localazy 🔗
You can now go to the Translations tab of your Localazy project and add new languages.
Localazy offers three main approaches to choose from and blend to translate your Storyblok content
- 💪🏻 Translate on your own or invite contributors - You can start translating on your own and use our built-in suggestion system.
- 🦾 Translate everything in bulk via machine translation - With the Localazy Autopilot plan, you can instantly translate all strings by running a machine translation over the content. This is great for the first iteration and localization testing of your Storyblok website.
- 🚩 Fully automate the translation process with the Continuous Localization services - Once your Localazy integration is set up, you can order translations from our vetted translators and get your project translated by professionals automatically. The service is also proactive, so you don't have to micromanage translators, and you can visit Localazy only once in a while to check the progress and sync the new translations.
If you have access to the pre-translate feature, I recommend you give it a try to test how the translation flow works quickly. Select which language you want to translate first and click on the menu to open the Pre-translate window.
In the next step, feel free to choose your favorite MT engine. Each of them can handle specific scenarios, terms, and tonality differently, and it cannot be said that one is always better than the other.
I'll go with DeepL for demonstration purposes since their API typically handles the translation request quite swiftly, and the quality is usually satisfactory.
Make sure to check the option Approve all translations so that you can use them immediately without having to review and accept them afterward. Check the other options to ensure that all the keys will be included in the pre-translate operation.
It could take a few seconds, but after a few page refreshes, you should see all three new languages fully translated.
While it has advanced rapidly over the last few years, remember that machine translation still has a long way to go to beat human professionals, especially in some languages, such as Hungarian and others. So keep in mind that this first quick test will likely yield subpar results. However, you can always order Professional translation services from our Continuous Localization Team later. 😄
Upload to Storyblok 🔗
Now that we have finished the translations. Let's upload the content back to Storyblok. Go to the Upload to Storyblok Tab and simply click the Upload Translated Content To Storyblok button. The process may take a while, depending on how much content is imported to Storyblok. All the content should be imported now!
You might want to double-check if all the languages uploaded to Storyblok are present in your Space using the language comparison table we discussed earlier.
Note: To add a language to your space, go to Space Settings ➡️ Configuration ➡️ Internationalization.
🎉 Enjoy the localized content 🔗
And that's it! You have successfully translated your Storyblok content using Localazy! Now, to see the localized content, there's nothing simpler than just browsing it.
✔️ Conclusion 🔗
We will be more than happy to hear the feedback on the Storyblok Integration and your company's needs so we can add new features and make the integration even more helpful and valuable to you!
Feel free to contact us at [email protected] or leave a comment below if you have any questions regarding this tutorial, the integration, or Localazy in general.
