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.

Tip

To learn more, check the Translations manual.

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

By default, publishing a story publishes all language versions simultaneously. To publish individual versions, open Settings → Internationalization → Publish individual translations and choose Enable individual translation publishing.

Enable translatable fields

To enable per-field translation (manual or AI-based), open the Block library and select the relevant block. Then, select the field and choose Translatable in the block’s Edit field tab. All field types except Blocks support translations.

Editors can enable the translation option for each field in each story version, and provide manual or AI translations.

Tip

To learn more, check the Translations manual.

Storyblok apps and integrations

Storyblok offers additional apps and integrations with translation management systems (TMS):

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

Identify the language loaded in the Visual Editor using the _storyblok_lang URL parameter.

Tip

To learn more, check the Manage the Visual Editor concept.

Build paths from translated slugs

The Translatable Slugs app stores a separate slug per language on each story and folder. To build a story’s real path from those slugs, install the Advanced Paths app, and call the @activeTranslatedSlug helper in the path template:

{{ @activeTranslatedSlug({ it }) /}}

The helper accepts three parameters:

Parameter	Type	Required	Default	Description
it	object	Yes	—	The template context, including the story, folder, and editor language
prependString	string	No	/	The string that prefixes the translated slug
fallbackSlugs	boolean	No	true	Whether to use simplified form of the language code

To change the prefix, pass prependString with a matching string. An empty string removes the leading slash:

{{ @activeTranslatedSlug({ it, prependString: '/new/' }) /}}
{{ @activeTranslatedSlug({ it, prependString: '' }) /}}

The helper resolves a slug in four steps:

1. Without an editor language, it returns the story or folder’s original slug.
2. With an editor language, it returns the matching entry from the story’s translated_slugs array.
3. With fallbackSlugs enabled and no exact match, it uses the language code, so es_co becomes es, and searches again.
4. Without any match, it returns the original slug.

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.

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 editor-friendly merge and overwrite functionalities.

Without Dimensions, set story alternates, and copy the content manually:

1. In Settings → Internationalization → Alternative Versions, choose Enable Alternative Versions.
2. In the Content section, create a folder structure and stories inside it.
3. Select the folder, choose Duplicate from the toolbar, and set Is alternative version of the duplicate.

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.

Tip

To learn more, check the Multi-Space Orchestration manual.

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