Internationalization

There are three main options for managing multi-language and multi-country content in Storyblok. Different use cases require different strategies, which is why Storyblok offers three different approaches:

• Field-level translation is a good choice if the structure of your content across different language versions is very similar or identical.
• Folder-level translation is preferable when content needs to be highly localized, 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 can have multiple language versions of each story. In practice, this means that you only need one story to manage and serve content in a variety of languages.

Setup

To set up field-level translations, navigate to Settings > Internationalization and configure one or more additional languages.

Once additional languages have been configured, a Languages menu will become available in the Visual Editor, right next to the History.

Note

In Settings > Internationalization, check Enable Individual Translation Publishing to independently publish a story's language versions. If left unchecked (default), publishing a story publishes all language versions simultaneously. Disabling the individual translation publishing setting after having used it does not affect the publication status of language versions.

Enable translatable fields

To enable a field to be translatable, navigate to the Block Library and select a field. In the Edit field section, check the Translatable option. Please note that Blocks fields are not translatable.

Once all desired fields have been configured accordingly, leaving the Block Library will reveal that every translatable field now has a toggle with a globe icon next to its name in the Edit section of the Visual Editor. This allows one to choose whether a translation should be provided for each instance. If the toggle is left inactive, its corresponding default language will be utilized.

Activating the toggle reveals a submenu in which you can show or hide the default language value, use the AI Translate feature, insert the default language value, go to Google Translate, or manually enter a translation.

Third-party services

The following integrations with third-party services are available:

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

Translatable slugs

Note

The Translatable Slugs app enables defining slugs for folders and stories in different languages.

Export and import of translations

Note

Export and Import functionality can be enabled by installing the Export Translatable Fields and Import Translatable Fields apps.

API

language parameter

A story's different language versions can be retrieved using the language parameter of the stories endpoint of the Content Delivery API.

// 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)
  })

fallback_lang parameter

The fallback_lang parameter can be utilized to specify a fallback language different from the default to use or untranslated fields.

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

Please note that for fallback_lang, the language code needs to be specified with underscores, even if it is defined with hyphens. E.g., es_co instead of es-co.

Retrieve all configured language codes

Use the spaces endpoint to retrieve an array of all language codes configured in the space.

Determine the current language in the Visual Editor

In the Visual Editor, it is possible to determine the current language based on the value of the _storyblok_lang parameter added to the iframe's src attribute. Learn more in the Visual Editor concept.

Folder-level translation

Folder-level translation uses separate, dedicated folders for each language, for example, one for English, one for German, and so on. This structure duplicates some of the content, but each localization can be customized entirely based on the structure and order of the story's components. Folder-level translation is particularly useful when there are considerable localization requirements.

Setup

To utilize folder-level translation, start by creating folders representing regions, markets, countries, languages, or other dimensions at the root level of the Content section in a space.

Dimensions app

Tip

The Dimensions app provides a convenient way to link alternative versions of stories across top-level folders. This approach allows for a high degree of autonomy and flexibility per story while offering convenient merge and overwrite functionality.

Combining field-level and folder-level translation

Furthermore, field-level and folder-level translation can be combined. This could be applicable when localized content needs to be offered in multiple languages. For instance, consider the scenario of two top-level folders set up as dimensions, US and EU. Both of these folders contain multiple stories whose content is localized (e.g., promoting products or services specifically available in the target market). In the US folder, the localized content could be served in different languages using field-level translation, say English and Spanish. Likewise, in the EU folder, the localized content could be served in, e.g., English, French, German, and Spanish.

API

All stories located within a folder can be retrieved using the starts_with parameter of the Content Delivery API.

// 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)
  })

For further information, please refer to Storyblok's API Documentation.

Space-level translation

Space-level translation uses multiple spaces to manage your content for different languages. Opting for space-level translation is advisable when dealing with projects of great complexity and size involving dedicated regions, markets, platforms, channels, and/or content editing teams. Using designated spaces in alignment with these factors provides a high degree of autonomy and flexibility. However, Storyblok's CLI (opens in a new window) and Management API (opens in a new window) ensure synergistic efficiency by making it possible to conveniently share components schemas, stories, datasources, and more across spaces.

AI-assisted translation

Note

See the AI assistance manual for further information.