Integrating Storyblok with Lokalise

Contents
    Try Storyblok

    Storyblok is the first headless CMS that works for developers & marketers alike.

    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.

    Imortant:

    Be aware that you need to upgrade to the Advanced Plan after the free trial is over to keep using the integration and many other features.

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

    Storyblok editing capabilities

    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.

    Storyblok editing capabilities

    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:

    Storyblok editing capabilities

    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:

    Storyblok editing capabilities

    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:

    Storyblok editing capabilities

    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:

    Storyblok editing capabilities

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

    Storyblok editing capabilities

    Personal access token

    Click Connect once again and enter your personal access token:

    Storyblok editing capabilities

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

    Storyblok editing capabilities

    Find the Personal access tokens section and select Generate new Token:

    Storyblok editing capabilities

    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!

    Warning:

    Don’t share the Personal access token with anyone or post them on any public space.

    Storyblok editing capabilities

    Importing content from Storyblok to Lokalise

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

    Storyblok editing capabilities

    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:

    Storyblok editing capabilities

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

    Storyblok editing capabilities

    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:

    Storyblok editing capabilities

    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:

    Storyblok editing capabilities

    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:

    Storyblok editing capabilities

    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:

    Storyblok editing capabilities

    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:

    Storyblok editing capabilities

    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:

    Storyblok editing capabilities

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

    Storyblok editing capabilities

    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:

    Storyblok editing capabilities

    Choose the languages you would like to export:

    Storyblok editing capabilities

    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:

    Storyblok editing capabilities

    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:

    Storyblok editing capabilities

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

    Storyblok editing capabilities

    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!