Skip to main content

International and multilingual sites with StoryBlok and Next.js. Part 1

StoryBlok is a unique headless CMS with a lot of nice features. This is a modern platform that combines the best solutions for building content-centric websites


StoryBlok is a unique headless CMS with a lot of nice features. This is a modern platform that combines the best solutions for building content-centric websites, in addition to the best preview functionality, it also has excellent flexibility and allows you to create business solutions for each individual client.

In the article below you will find information on:

  • how you can use StoryBlok to create a global multilingual resource
  • how to work with huge portals that have different markets in different countries, and also
  • separate features and solutions for different regions.


The challenge we want to cover here is to create a global website that should support different languages and different content for individual regions. It also should have excellent SEO metrics, as well as best page speed metrics. The website should have clear and easy-to-use headless CMS, working with everything from one account, and have only one domain!



  • Organize a StoryBlok account to work with different regions and languages
  • Create Next.js project and connect it to CMS
  • Organize SEO and make sure that every user gets what they need

Storyblok account

Since the main part of our discussion is the process of organizing work with different languages and countries, we will not deal with the main aspects of working with StoryBlok, but will immediately move on to the part that is interesting to us. Full information can be found in the documentation

Ways of working with translations in StoryBlok

StoryBlok has 3 approaches to organizing work with languages:

  • translations at the field level in the document
  • translations at the folder level inside the account
  • translations at the level of different StoryBlok spaces

We will consider in detail only one of them, which fits our purpose. However, below you can read a brief information about each of them to have a full understanding of whether you are on the right path.

If your website does not plan to have different content for different countries (users should not have pages or features personalized for the region), an excellent choice would be the translation approach at the field level in the document. This approach is perfectly described in the documentation

If you already have several StoryBlok spaces, then you can use them as separate language versions. One space will be responsible for one region, the other one is for another region.

The last method is the one of organizing translations at the folder level. In this method, we get the flexibility to create different content for different regions, and also with this option there is no need to create different StoryBlok spaces, which allow us not to worry about reusing content developments and components from one space to another. We will consider it below.

Getting started

To be clear, a new StoryBlok account will be used, where we will take a look at all the steps. The main part of the work will take place in the home folder of our content.

Storyblok localization image1 So supposing, our resources should work in 3 countries. For example, it will be Germany, France and Italy. We want to have our own set of languages in each of the markets.

  • Germany: German(de), English(en)
  • Francy: French(fr), German(en), English(en)
  • Italy: Italian(it)

To work with content for different countries, we will rely on Google's documentation and recommendations

To make it clear to search bots about which country and language the page belongs to, there are a number of requirements that must be met. In our case, when we want to have 1 domain and control different countries and languages, the best choice would be to have information about the country and language in the URL and represent this data in meta tags. This way bots will understand and index our pages correctly.

As a result, we need the URl to contain key-value pairs in the language-country format. Detailed information about this can be found here

Given the information described above and our requirements, we must have the following prefixes:

  • Germany: de, en-de
  • France: fr, de-fr, en-fr
  • Italy: it

Each page of our resource will contain in the URL some of the prefixes described above. This will be the basis of our localization logic. The next step is to create this structure in StoryBlok.

Creating folders for different locales

We need to reflect our locale system in StoryBlok, and the best way to do this is to use folders. As a result, we will get a set of key-value folders with a display of each pair from the last step.

!Attention The folder slug must clearly match the key (en-de). The name can be any string.

Storyblok Localization image 2

After we have completed the structure, let's make a home page inside one of the folders.

Storyblok localization image 3

This is a very simple document that only has a Title & Description. This will be quite enough for a demo

Storyblok Localization image 4

For the convenience of working with different versions of pages, as well as, very importantly, linking them together, we will use the StoryBlok application dimensions

It is easy to add it in the applications tab in your

Storyblok Localization image 5

After adding this application, we will be able to easily copy/update pages

Storyblok Localization

For instance, by clicking on clone to all, we can easily create linked copies of this page in other locale folders

Storyblok Localization image 7

If we check other folders, we will find out that copies of this page have been created everywhere. This is convenient when we want to keep the structure of the content within a certain market, so we don't need to copy or fill it twice, just translate or add changes. By the same logic, the merge of changes works, we can determine the work of the merge, indicating, for example, whether it is necessary to grind the old values.

This was the first part in a series of “Storyblok localization with NextJS”. In the second part we will dive deeper into NextJS middleware and localization configurations


Alex Hramovich

Alex Hramovich

TechLead at FocusReactive