How to setup field and folder level translation

Have you ever wondered how to create translations for different languages? Storyblok provides support for content in different languages using our internationalization (opens in a new window) options, such as field (opens in a new window) , folder (opens in a new window) and space (opens in a new window) level translations.

In this tutorial, we will look at how to setup fields and folder level applications on Storyblok.

Field level translation

First, we need to set the new language we want our content translated to under the Languages {1} tab in settings {2}. By default, translated versions get published with the default language if present unless you change it in the Languages tab.

Now, let’s define which fields are translatable in the schema of each component. At the top bar, you will see a list of languages you can translate to when you click on default {1}.

To make a field translatable, navigate to Block Library {1}, pick the block {2} and choose the field {3} you want to make translatable in the checkbox.

Once the field is enabled for translations, switching the language in the UI allows you to add a translation for each previously activated field separately. Fields that are not enabled for translation are included but use the default language in every story.

To translate the content in the field, activate the checkbox and add your content. Click on the small arrow to unveil additional options to make editing translations easier. When the menu opens, the text in the default language is shown to support the translation.

Translatable slugs

When using field-level translations there is often the requirement to translate the slug of a story as well. You do not need to switch to folder-level translation if this comes up in your project. With the translatable slugs app, it is possible to define slugs for folders and stories in different languages. You can also translate the name of the entry too with your app.

Visit the Storyblok App Store to install Translatable Slugs (opens in a new window) in your space.

Custom Fallback Language

This feature allows you to define a custom fallback language if you use field-level translations using the parameter fallback_lang. This is useful, for example you can make an API call to get the German version of your content and use Japanese as fallback. if that German doesn’t exist it will fall back to using Japanese and if it does not exist it will use the default language defined in the space settings.

Setting up Folder Level Translation

To use folder level translation, you need to create folders at the root level of your content repository. These folders represent the language, country version of your content or any other level of variation.

Duplicate your stories and folders into the folders we just created like this.

Choose the folder you want to duplicate it to.

Defining alternative versions is necessary to link between different translations of your content. When looking at how these links work with the API we need to look at two properties. group_id is a unique ID that is used to cross reference all stories that belong together. The group_id is then used to populate the alternates property which was added to the response for your convenience. alternates contains an array of UUIDs for stories which have the same group_id as the current story. With these two properties you should have all the information you need to build an application that is translated using folder level translation.

E.g

        
      GET api.storyblok.com/v1/cdn/stories/(:full_slug|:id|:uuid)
    

Response:

        
      {
    "story": {
        "name": "Story Name",
        // group id defines the referenced alternates
        "group_id": "fb33b858-277f-4690-81fb-e0a080bd39ac",
        // resolved alternates by group_id
        "alternates": [],
    }
    ...
}
    

Alternatively, we recommend installing the Dimensions app (opens in a new window) to create links between stories in different languages. These links are needed to find alternate versions of a story. In the context of a web application, HTML tags, HTTP headers or sitemaps can be used to inform search engines about these alternate versions (hreflang) (opens in a new window) . After installing the app, there will be a tree icon in the top right corner of the content editor.

The drop-down menu will show a list of folders and connected alternative versions. The screenshot shows different actions that are available. The table below to show all possible actions and an explanation.

API and Data Structure

Using the storyblok-react (opens in a new window) , we can fetch stories in specific languages like this.

        
      import { storyblokInit, apiPlugin } from "@storyblok/js";

const { storyblokApi } = storyblokInit({
  accessToken: "YOUR_ACCESS_TOKEN",
  use: [apiPlugin],
});

const { data } = await storyblokApi.get("cdn/stories", { version: "draft", language: "ja" });
    

Using GraphQL

        
      {
    PageItem(id: "home", language: "ja") {
      id
      slug
      content {
        _uid
        component
        body
      }
    }
  }
    

Conclusion

We’ve now gone over how to setup translations at folder and field level. We also looked at translatable slugs and how to use them for translation in applications on Storyblok. Another way of translating is using space level translations. This involves using multiple spaces to manage your content in different languages. For example, you can have Space-A for your content in French and Space B for your content in German and if there’s a need to share components, story, schema, etc, you can use the Storyblok CLI (opens in a new window) and management API (opens in a new window) .