Almost EVERYONE who tried headless systems said they saw benefits. Download the state of CMS now!

O’Reilly Report: Decoupled Applications and Composable Web Architectures - Download Now

Empower your teams & get a 582% ROI: See Storyblok's CMS in action

Skip to main content

Internationalization

Outdated:

This documentation is out of date. Please checkout our new documentation: Internationalization about this topic.

There are a few options to manage multi-language and multi-country content in Storyblok. Option 1 is a good decision if you have most of your content translated. Consider using option 2 if the content tree is different in every language.

Option 1: Single tree and field level translation

Storyblok can store multilanguage content on the field level. This means you only need one content tree. A single tree stores each translation as a property under the same content item.

As long as your site content is very similar from one language to another, this is the best option. You will have fewer pages to manage and the system takes care of serving the correct language automatically.

Setup

In order to setup field level translation you need to add languages under the tab "Languages" in the space settings and define set the fields to translatable in the schema configuration of each component. Once you configured the languages you should see a language switch like in the following screenshot.

Field Level Translation Dropdown

API-access

You can access the localized version of the content by prepending the language code to your api requests. Following a few examples.

Default version:
api.storyblok.com/v1/cdn/stories/home
Localized version Api V2:
api.storyblok.com/v2/cdn/stories/home?language=de
Localized version Api V1:
api.storyblok.com/v1/cdn/stories/de/home

Default version:
api.storyblok.com/v1/cdn/stories?starts_with=news
Localized version Api V2:
api.storyblok.com/v1/cdn/stories?starts_with=news&language=de
Localized version Api V1:
api.storyblok.com/v1/cdn/stories?starts_with=de/news

Important: If you need translated slugs (rather than prefixed with the {locale}/slug) for different languages your can use a custom field and resolve it in your implementation by loading the stories according to the uuid in the links. Slugs are currently not translated in this options.

Important: Make sure to not use both blocks field type and nested translated field in combination as that will add a second layer of translations which will cause your editors to have multiple different blocks that are translatable but for each language there will be multiple language versions - so those two should not be used together. If you want to use different slugs for different languages out of the box, you can go for the next option below.

Option 2: Multiple trees

This structure consists of separate content trees, one for each language. One content tree for English, another for German and so on. This effectively duplicates some content but allows completely customized local content.

This option is also optimal when the content for each language is managed by separate teams or your website or app is organized differently for each language.

Setup

First you will need to create folders at the root level of your content repository. They represent each language or country version of your content.

Folder Structure

To make it easier to create a linkage between the alternative versions of each language you can install the "Dimensions" app. This will add a tree icon to the top right corner of the content editor.

The submenu show a list of folders and the connected alternative versions. When clicking "Create" a new content item will be duplicated from the current content item.

Dimensions Dropdown