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.

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.

AI translation

Third-party services

The following integrations with third-party services are available:

• DeepL
• Lokalise
• Localazy
• Smartling
• LingoHub

Translatable slugs

Export and import of translations

API

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

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

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

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

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.

        
      https://api.storyblok.com/v2/cdn/stories?starts_with=germany

    

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 and Management API ensure synergistic efficiency by making it possible to conveniently share components schemas, stories, datasources, and more across spaces.