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

Introduction

Storyblok CMS is a unique headless CMS with a large number of advanced features. This is a modern platform that combines the best solutions for building content-centric websites. Its best-in-class preview functionality, as well as excellent flexibility, allows you to create a business solutions for each individual client.

The series of articles “Storyblok localization with Next.js” provides an in-depth guide on multilingual functionality in Storyblok and steps to implement it.

In the first part of the series you will learn about translation approaches Storyblok has, what’s the difference between them, and how to choose the one for you. We will walk you through the steps of defining URI structure, creating pages for different languages and markets and show you how to manage them.

The second part will cover the technical part, including how to set up the latest Next.js project and connect it to Storyblok. We will cover what code you need to add to handle markets and languages pages, which metatags are important and how to make sure users see the correct page.

The final project is suitable for small companies as well as huge enterprise clients, demonstrating the scalability and robustness of the examined approach.

Goals

The challenge we want to cover here is to create a global website that supports different languages. It also should have excellent SEO metrics, and the 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!

Tools

• Storyblok
• NextJS

Plan

• Determine correct URI structure suitable for SEO
• Set up Storyblok space to have different regions and languages
• Install Storyblok app to simplify pages management
• 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 goal is to not overview features but set up a project with different languages and countries, let’s jump right into it. If you are interested in other features or less familiar with Storyblok CMS, check out full documentation.

Ways of working with translations in Storyblok

Storyblok has 3 approaches to organize work with languages:

• translations at the field level in the document
• translations at the folder level in the space
• combined field and folder level translations
• translations at the spaces level in the account

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 and all the languages in the region. The same for all other regions.

Another method is translation at the folder level. In this method, we get the flexibility to create different content for different regions, and there is no need to create different Storyblok spaces. This allows us not to worry about reusing content developments and components between spaces. Today we are going to use that.

And the combination of field and folder level translations. It offers the most flexible yet complex approach, organizing content in language-specific folders while also allowing field-level translations within each document. It is the best when you want to create region-specific content while maintaining granular control over individual text elements.

Getting started

We are going to use a new Storyblok space, where we will take a look at all the steps. Once you create a new space you should land in the root folder.

Storyblok localization image1

Let’s say the resources should work in 3 countries: Germany, France and Italy. In addition to that we want to have a custom set of languages for each country.

• 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 effectively communicate region and language to search bots and web crawlers, we must meet some requirements.

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 properly.

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 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 structure 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

We recommend to use this app to simplify the process, although it's not mandatory.

Storyblok Localization image 5

After adding this app, we will be able to easily copy and update pages. Find dimensions settings under the language dropdown in the top control bar.

Storyblok Localization

For instance, by clicking on clone to all, we can easily create linked copies of this page in other locale folders. Let’s do it.

Storyblok Localization image 7

If we check other folders, we will find out that copies of this page have been created. This is convenient way to keep the structure of the content consistent across countries and languages without manual work. Now you are able to translate content or apply changes to the pages.

When you already have existing pages for certain locales, it’s possible to merge two pages together. This functionality offers convenient overwrite functionality, and allows to determine which fields should be persisted.

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