Internationalization

Storyblok offers three approaches to manage multilingual and multi-country content. Choose the strategy that best matches your use case:

• Field-level translation is a good choice if the structure of your content across different language versions is similar or identical.
• Folder-level translation is preferable when content varies by locale, necessitating structural differences across versions.
• Space-level translation is an effective solution if multiple content editing teams work on dedicated platforms and channels with high localization and customization requirements.

Field-level translation

Storyblok supports multiple language versions of each story. In practice, this means that you only need one story to manage and serve content in multiple languages.

Set up field-level translation

To set up field-level translations, open Settings → Internationalization and add one or more additional languages.

Once configured, open the Visual Editor, and select the desired version from the Languages menu at the top.

Customize flag display

By default, Storyblok shows a flag icon next to each language in the Languages menu to help editors distinguish between locales. To switch to a country-based icon instead of a language-based one, or to hide all flags, open Settings → Internationalization → Flag display and set your preference.

Note

By default, publishing a story publishes all language versions simultaneously. To publish individual versions, open Settings → Internationalization and select Enable Individual Translation Publishing.

Enable translatable fields

To enable per-field translation, open the Block library and select a field. In the Edit field section, enable the Translatable option. All field types except Blocks fields support this option.

Back in the Visual Editor, select the relevant language from the Languages menu. Every translatable field now has a toggle with a globe icon next to its name. Editors can enable the translation option for each field in each story version. When disabled, the default language applies.

Activating the toggle reveals a menu: hide or show the default language value, translate using AI, insert the default language value, open Google Translate, or manually enter a translation.

Third-party integrations

The following integrations with third-party services are available:

• Lokalise
• Smartling
• Localazy
• LingoHub
• Crowdin
• DeepL

Storyblok apps

• Use the Translatable Slugs app to define folders and stories slugs in different languages.
• Use the Export Translatable Fields and Import Translatable Fields apps to export and import translations from third-party services (in XML and JSON formats).

Fetch field-level content

The Content Delivery API’s stories endpoint offers two relevant parameters.

The language parameter

Retrieve a story’s language version using the language parameter:

// Using the Universal JavaScript Client:
// https://github.com/storyblok/storyblok-js-client
Storyblok.get("cdn/stories/home", {
  language: "es",
  version: "published",
})
  .then((response) => {
    console.log(response);
  })
  .catch((error) => {
    console.log(error);
  });

The fallback_lang parameter

Specify a fallback language for untranslated fields using the fallback_lang parameter:

// Using the Universal JavaScript Client:
// https://github.com/storyblok/storyblok-js-client
Storyblok.get("cdn/stories/home", {
  language: "es-co",
  fallback_lang: "es",
  version: "published",
})
  .then((response) => {
    console.log(response);
  })
  .catch((error) => {
    console.log(error);
  });

Caution

You must set a language code with underscores. For example, es_co instead of es-co.

Fetch all language codes

To retrieve an array of all language codes configured in the space, use the Content Delivery API’s spaces endpoint language_codes parameter.

Tip

You can determine which story language is loaded in the Visual Editor based on the value of the _storyblok_lang appended to the preview URL. Learn more in the Visual Editor concept.

Folder-level translation

Folder-level translation uses separate, dedicated folders for each language. This structure duplicates some content, but allows customization of each locale based on the story components’ structure and order. Folder-level translation is particularly useful for complex localization requirements.

Set up folder-level translation

To use folder-level translation, open the Content section and create folders that represent the project’s structure (for example, regions, markets, languages, etc.) at the root level.

Tip

The Dimensions app provides a convenient way to link alternative versions of stories across top-level folders. This approach combines a high degree of autonomy and flexibility per story with convenient merge and overwrite functionalities.

Fetch folder-level content

To retrieve all stories in a folder, use the starts_with parameter of the Content Delivery API’s stories endpoint:

// Using the Universal JavaScript Client:
// https://github.com/storyblok/storyblok-js-client
Storyblok.get('cdn/stories/home', {
  starts_with: 'european-union'
  version: 'published',
})
  .then(response => {
    console.log(response)
  }).catch(error => {
    console.log(error)
  })

Combine field-level and folder-level translation

You can combine field-level and folder-level translations. A good use case is when you offer localized content in multiple languages for different markets.

For example, consider the scenario of two top-level folders—US and EU. Each folder contains localized stories, such as products or services available in the target market. The stories themselves use field-level translation:

• The US folder contains stories in English and Spanish.
• The EU folder contains stories in English, Spanish, French, and German.

Space-level translation

Space-level translation uses multiple spaces to manage translated stories. Use this approach for complex, large-scale projects that serve regions, markets, platforms, channels, or content editing teams that require autonomy and flexibility.

Use Storyblok’s CLI and Management API to sync and share components schemas (blocks), stories, datasources, and more across spaces.