---
title: Internationalization
description: Manage multilingual content in your space. Choose the strategy that best matches your use case: field-level translation, folder-level translation, or space-level translation.
url: https://www.storyblok.com/docs/concepts/internationalization
---

# Internationalization

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

-   [Field-level translation](#field-level-translation) is a good choice if the structure of your content across different language versions is similar or identical.
-   [Folder-level translation](#folder-level-translation) is preferable when content varies 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 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](/docs/manuals/ai-assistance#ai-translations), 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](https://lokalise.com/product/apps/content-management/storyblok)
-   [Smartling](https://www.storyblok.com/apps/storyblok-gmbh@smartling)
-   [Localazy](https://www.storyblok.com/apps/external/localazy)
-   [LingoHub](https://help.lingohub.com/en/articles/9389200-how-to-set-up-storyblok-integration)
-   [Crowdin](https://www.storyblok.com/apps/external/crowdin)
-   [DeepL](https://www.storyblok.com/mp/storyblok-ai-suite-virtual-identity#b-deepl-content-translation-app-for-storyblok-b)

#### Storyblok apps

-   Use the [Translatable Slugs app](https://www.storyblok.com/apps/translatable-slugs) to define folders and stories slugs in different languages.
-   Use the [Export Translatable Fields](https://www.storyblok.com/apps/export) and [Import Translatable Fields](https://www.storyblok.com/apps/import) 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](/docs/api/content-delivery/v2/stories/retrieve-a-single-story) offers two relevant parameters.

#### The `language` parameter

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

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

#### The `fallback_lang` parameter

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

```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]
> 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](/docs/api/content-delivery/v2/spaces/retrieve-current-space) `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](/docs/concepts/visual-editor#preview-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.

> [!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 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](/docs/api/content-delivery/v2/stories/examples/retrieving-stories-from-a-folder):

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

## 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](/docs/libraries/storyblok-cli) and [Management API](/docs/api/management) to sync and share components schemas (blocks), stories, datasources, and more across spaces.

## Pagination

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