Integrating Storyblok with Lokalise

In this article you’ll learn how to integrate Storyblok with Lokalise to make your content translation process faster and much more convenient. But, what is Lokalise? I hear you ask. It is a feature-rich localization and translation management platform that offers tools for translators, managers, developers, and designers, namely:

• The ability to manage translations using a convenient graphical user interface across your team.

• The ability to assign tasks to team members, define various automation and quality assurance rules, create project branches, and much more.

• A vast array of integrations with third-party services and software including GitHub, Amazon S3, Trello, Figma, Adobe XD, and, of course, Storyblok.

• Software development kits for mobile applications and client libraries for our API.

Lokalise is here to get your translations done, and offers flexible subscription plans. Intrigued? Then let’s begin!

Preparations

Registration

To get started, you will need to create a new account with Lokalise if you don’t have one already. Grab your free trial here (no credit card is required), enter your details like your name and email, and complete the registration.

After logging in to the system, you’ll see the following page:

This is your dashboard and it lists all the available translation projects in your current team. What’s the difference between a team and a project? Nothing too complex, really:

• A team includes projects, global settings, and members (users). Once you have registered on Lokalise, a new team is created for you automatically and initially only your account is added as a member of this team. As a team creator, you have full access to all team settings and projects. Later, of course, you may invite more users and grant them certain access rights. Finally, each team has its own subscription plan that you may upgrade or downgrade as needed.

• A project belongs to a team. It includes your translations, languages, screenshots, glossary entries, integration settings, quality assurance rules, and other data. Usually one project contains all the translations for a single website or a mobile application. As mentioned above, you have full access to all projects within your team, It is also possible to invite additional users and grant them certain access rights to specific projects. You can create as many projects as you require within a team.

In the screenshot above you can see that I have two projects called “Storyblok” and “Sample Project”. Each project has a list of associated languages, and for each language the current translation progress is displayed.

Creating a new project

Go ahead and create a new translation project by clicking the New project button or pressing the Ctrl + P (Cmd + P) shortcut.

Fill in the following fields:

• Project name — enter any name you’d like. I’ll name my project “Personal content”.

• Description — optionally, you can explain the purpose of your project.

• Base language — choose the primary language. It should match the primary of your content in Storyblok. I’ll keep “English”.

• Options — for now you can leave options as is. To make a long story short, “Reviewing” means assigning a special “reviewed” status to your translations. Usually, this means that translations were double-checked and proofread by one of your teammates or a freelancer.

• Project type — set to Localization files. The Documents type is used in cases where you’d like to translate Word or HTML files.

When you are ready, hit Proceed.

Project editor

After the project is created, you will see the following screen:

This is the project editor where you will manage your translations, languages, and other aspects of your project. While this editor might look a bit complex at first (there are many unusual icons and buttons), you’ll find yourself working with it like a pro in no time.

Adding content languages

Now let’s switch from Lokalise to Storyblok for a moment. Open your Storyblok board and proceed to Settings > Languages:

Here you can set a default language for your content and add other languages into which you would like to translate. In the example above, I have English set as the default language along with two additional ones: Russian and Spanish.

After you have adjusted the language settings, hit Save. Before returning to Lokalise, make sure to adjust the content schema properly. Specifically, make sure that all fields you are going to translate are marked as Translatable:

Now you can return to Lokalise!

Setting up a new integration

At this point, we are ready to integrate Storyblok with Lokalise. First, click on the More button (…) and choose Integrations:

Use the search box in the top right corner to find the “Storyblok” integration. Hit Connect:

Personal access token

Click Connect once again and enter your personal access token:

To obtain a personal access token, return to Storyblok, click the small arrow in the top left corner, and then choose My account:

Find the Personal access tokens section and select 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 disclosed publicly!

Importing content from Storyblok to Lokalise

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

Here, choose your Storyblok space and the base language of your content. When you are ready, press 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 the following icon:

After the refresh process is completed, you’ll see this notification message:

To start translating your content in Lokalise, you’ll need to import the desired items first. To achieve this, 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 only available in English, then you can remove all other languages from this list as the corresponding translations will be empty anyway.

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

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

Managing translations

Now return to the project editor by clicking on the project name in the top left corner. Then, you will see all the imported content, for example:

Tags

The long alphanumeric values to the left are called translation keys: basically, they act as special identifiers to properly connect your translations in Lokalise with the content in Storyblok. Do not change these translation keys as doing so may lead to various technical issues.

Each translation key has a handful of tags represented by colored labels:

• First Post (orange) — this is the name of my entry on Storyblok.

• My Post (dark blue) — the content type.

• Storyblok (fuschia) — this tag simply means that the content was downloaded from Storyblok.

You may use these tags to filter your translations. To achieve this, click Filter > Tag and choose the tags you are interested in:

Performing translations

Now, how do you translate something? It’s really simple: just click on the text next to the desired language. For instance, I’d like to translate the welcome post into Russian:

After clicking on the word Empty, you’ll be presented with a text input like so:

Simply enter your translation in that text field and click the Check button. Moreover, you’ll see machine translation suggestions, namely from Google Translate, DeepL, and Bing. To use one of the suggested versions, simply click it.

Exporting content from Lokalise to Storyblok

Once you have translated the content, you’ll need to export it back to Storyblok. To do this, click More > Integrations again and open the Storyblok integration.

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

Choose the languages you would like to export:

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

Checking the result

At this point you can return to Storyblok and check out the result! For example, I have opened my first blog post to make sure that its title and body were translated properly:

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

Conclusion

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

If you would like to learn more about Lokalise features, I would recommend checking out our “Getting started” guides that cover all the basic features and demonstrate these concepts in practice using screenshots and videos. More advanced topics are also covered in our docs, but if you find yourself struggling, please don’t hesitate to reach out to our support team as well.

That’s it for today, folks. Thank you for reading this post and see you soon on Lokalise!