Skip to main content

International and multilingual sites with Storyblok and Next.js. Part 2

This is the second part of the series of "Storyblok Localization" Series

This is the seconds part of International and multilingual sites with Storyblok and Next.js series

Initialization of the project

You can find all the examples in the Storyblok documentation

Main steps: Create Next.js project Connect Storyblok

After completing these steps, we will be able to see the pages we created earlier

NextJS image 1

<link rel="alternate" href="" hreflang="en-gb" />

By following the link, we can refer to the Google documentation to have a complete understanding of how this mechanism works. To describe it in a nutshell, we need to link to ALL other language versions of the same page in each page, as well as link to this page (this is necessary for protection so that third-party resources cannot link to you without your approval). This will give the bot an understanding of which region and which user which page needs to be given

Due to the fact that we create pages using the Dimensions application, our pages are already automatically linked, this can be seen in the page settings.

NextJS image 2

!Attention If you do not want to use the Dimensions app, you must create the connection manually. This is a very important and mandatory part of the process.

All this data is easy to get on the page, and it will be available in the “alternates" field. All we have to do is create the links. Here is the example of the SEO component code to implement.

NextJS image 3

After adding the code to the page, we need to check that all the links are installed correctly. As a result, you should get a set with all copies of the page, including the one we are currently on.

NextJS image 4 Upon completion of this, we will be ready for the fact that search bots will understand which pages and who needs to be given. We shouldn’t also forget about the other tags that help bots better understand the page they see

Home page

We did everything we needed to separate the content and teach bots to understand our resources. The only thing that remains is to make sure that a person visiting the home page of the site, for instance was directed to the version he needed. If a person searches for our site in google search, he probably won't even get to it, because there will be correct localization versions for him. But if a person tries to enter the page in a direct way, it would be a good tone to give him the most suitable page.

There are several solutions. One of them is just to set up a redirect to the default country and language. The other is to use logic that, based on the geo position of the user and the languages that suit him, will give the page that he needs.

In this example, we will consider using Next.js middleware, but you can use any other tool that will allow you to perform a small amount of JS immediately before giving the page to the end user. It can be Cloudflare worker or AWS Lambda/Edge functions.

NextJS middleware

To start using it, you need Next.js versions higher than 12.1. The detailed documentation may be found by following the link, but we will consider only the part that we need for implementation

To begin with, we need to create a file named middleware.js at the root of the project. After that, just copy the default material from the documentation into it.

NExtJS image 5

We will conduct the following steps:

  • Make sure that our middleware will handle only those routes that you need
  • Define the person's country
  • Determine the languages suitable for the user
  • Define the most suitable homepage for him
  • Direct the user to the page that he should receive

Filtering routes

We need to make sure that we are calling our middleware only for the home page. We don't want other requests to go through this logic, because they simply don't need it.

Let's update the middleware code and config so that it meets our needs.

NextJS image 6

After this action, our middleware will only work with the root query, which is exactly what we wanted

User's country

To determine the user's country, we will use the information from the request object of our middleware. More detailed

NextJS image 7

User’s languages

To determine the appropriate languages, the Accept-Language header is best suited. In it you will be able to find information about the user's preferred languages. You can read more details here

In this header we will have a string of this type:

< Accept-Language: fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5 />

All that remains for us to do is to compare the available information with the content we have in our CMS

Determining the correct home page version

To begin with, we will load our default homepage by creating 2 functions that will help us make requests. fetchSpaceInfo is needed r to get the cache version to be sure that we get the latest version of the content. fetchStory is a common function that can fetch a story.

NextJS image 8

After that, we can start loading the home page.

NextJS image 9


Make sure that the page you are trying to get is published. You can also fetch drafts, but you need to be careful and clearly understand what you are doing.

When we get the default homepage, we will be able to see that it already includes the alternates section, which we used to form tags in the first part of this article.

Based on the information from this section, we can understand what we need to give to the user.

We will make a function that will select the most appropriate version based on the data obtained above. The idea of it is to compare the data of the country, language and our content. We will make only a basic version, but remember that you can update the logic at any time, making it more unique or optimized.

NextJS image 10

After creating such a function, we just need to call it and return the most appropriate version to the user

NextJS image 11

Given that we have no information about the country during local development, the default value will be taken.

In my case, the language header has only 2 values en-GB, en. Therefore, under these conditions, when I try to open a page,get a page with a DE marker, as well as the EN language, which fully meets expectations.

NextJS image 12

The last step and a good tone would be to put a cookie to the user about the preferred version of the page, so that in the future we do not start the country search process from scratch. We will not consider this in this article, but we will leave a link to the documentation where you can read how to do this. LINK


At the end of the setup, you get the following result:

  • You have an easy-to-use and intuitive CMS.
  • The ability to keep several countries in 1 account.
  • Your managers will always see a clear URL structure that will help prevent unnecessary mistakes.
  • It is also possible to restrict access to different folders at the Storyblok role level.An easy-to-understand frontend project where the logical parts are clearly separated.
  • You have pages that work in static mode with the Storyblok API, as well as separate logic that helps to deliver content correctly and does not have a strong impact on the speed of work due to its placement on edge servers close to the user, as well as the speed of execution.

NextJS images 13

Ready to explore your Headless opportunities? Contact our experienced team to shift your business to the tech of the future.


Alex Hramovich

Alex Hramovich

TechLead at FocusReactive