---
title: Internationalization
description: Discover Storyblok's documentation with comprehensive developer guides, user manuals, API references, and examples to help you get the most out of the headless CMS platform.
url: https://storyblok.com/docs/concepts/internationalization
---

# 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](#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](#folder-level-translation) is preferable when content varies greatly by locale, necessitating structural differences across versions.
-   [Space-level translation](#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 various languages.

### Set up field-level translation

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]
> To independently publish a story's language versions, open **Settings** → **Internationalization** and check the **Enable Individual Translation Publishing** option. 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. 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 users to choose whether a translation should be provided for each instance. If the toggle is left inactive, the corresponding default language applies.

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, use Google Translate, or manually enter a translation.

### Third-party services

The following integrations with third-party services are available:

-   [DeepL](https://www.storyblok.com/mp/storyblok-ai-suite-virtual-identity#b-deepl-content-translation-app-for-storyblok-b)
-   [Lokalise](https://lokalise.com/product/apps/content-management/storyblok)
-   [Localazy](https://www.storyblok.com/apps/external/localazy)
-   [Smartling](https://www.storyblok.com/apps/storyblok-gmbh@smartling)
-   [LingoHub](https://help.lingohub.com/en/articles/9389200-how-to-set-up-storyblok-integration)
-   [Crowdin](https://www.storyblok.com/apps/external/crowdin)

### Translatable slugs

> [!NOTE]
> The [Translatable Slugs app](https://www.storyblok.com/apps/translatable-slugs) enables defining slugs for folders and stories in different languages.

### Export and import of translations

> [!NOTE]
> To enable export and import functionality, install the [Export Translatable Fields](https://www.storyblok.com/apps/export) and [Import Translatable Fields](https://www.storyblok.com/apps/import) apps.

### Fetch translated content

#### `language` parameter

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

```javascript
// 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.

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

> [!WARNING]
> When using `fallback_lang`, the language code needs to be specified with underscores, even if it's defined with hyphens. For example, `es_co` instead of `es-co`.

### Retrieve all configured language codes

Use the [spaces endpoint](https://www.storyblok.com/docs/api/content-delivery/v2/spaces/retrieve-current-space) 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](/docs/concepts/visual-editor).

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

### Set up folder-level translation

To use folder-level translation, first create 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](https://www.storyblok.com/apps/locales) 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.

### Combine 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 (for example, 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 English, French, German, and Spanish.

### Fetch folder-level content

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

```javascript
// 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](https://www.storyblok.com/docs/api/content-delivery/v2/getting-started/introduction).

## 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](https://www.storyblok.com/docs/Guides/command-line-interface) and [Management API](https://www.storyblok.com/docs/api/management/getting-started/introduction) ensure synergistic efficiency by making it possible to conveniently share components schemas, stories, datasources, and more across spaces.

## AI-assisted translation

> [!NOTE]
> Check the [AI assistance manual](/docs/manuals/ai-assistance#ai-translations) for further information.

## Pagination

-   [Previous: FlowMotion](/docs/concepts/flowmotion)
-   [Next: References](/docs/concepts/references)