How to setup field and folder level translation

Contents
    Try Storyblok

    Storyblok is the first headless CMS that works for developers & marketers alike.

    Have you ever wondered how to create translations for different languages? Storyblok provides support for content in different languages using our internationalization options, such as field, folder and space 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.

    app.storyblok.com
    Choosing languages on Storyblok settings tab
    1
    2

    Choosing languages on Storyblok settings 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}.

    app.storyblok.com
    Translating languages on Storyblok
    1

    Translating languages on Storyblok

    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.

    app.storyblok.com
    Making fields translatable on Storyblok
    1
    2
    3

    Making fields translatable on Storyblok

    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 in your space.

    app.storyblok.com
    Using translatable slugs for field level translations

    Using translatable slugs for field level translations

    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.

    HINT:

    You can learn more about field-level translation here.

    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.

    app.storyblok.com
    Setting up folder-level translation

    Setting up folder-level translation

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

    Copying stories to folders in Storyblok

    Copying stories to folders in Storyblok

    Choose the folder you want to duplicate it to.

    Duplicating stories in folders for folder-level translations

    Duplicating stories in folders for folder-level translations

    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 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). After installing the app, there will be a tree icon in the top right corner of the content editor.

    Translating stories with folder level translation

    Translating stories with folder level translation

    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.

    Action Description
    Clone to all Duplicate the current story into all available folders.
    Merge to all Merge the changes into all connected stories.
    Overwrite Overwrite the existing story in the folder with the current story.
    Merge Merge the changes to the selected story.
    Create clone Use the current story to generate a duplicate in the selected folder

    API and Data Structure

    Using the storyblok-react, 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 and management API.