Creating Seamless Multilingual Experiences with Storyblok's Internationalization

When I think about internationalization in Storyblok CMS, it’s really about managing content so it works for multiple languages and regions. It’s the process I use to adapt my content, making it accessible and meaningful to people all over the world. Internationalization ensures that users in different countries can engage with my content in a way that feels natural to them.

Storyblok’s headless CMS architecture plays a big role here, and I find it fascinating how well it supports this. In a headless CMS, the content I create is separated from how it’s displayed. I can manage translations, adjust regional settings, and push content out seamlessly, all thanks to how Storyblok is built.

First off, it’s a key to reaching diverse audiences. If you only publish content in one language, you’re missing out on connecting with people who don’t speak it. By offering my content in multiple languages, you can tap into new markets and grow your reach, whether that’s attracting readers, customers, or partners from different parts of the world.

It also makes a huge difference to the user experience. When someone visits such a site and sees content in their language, they’re more likely to stick around, explore, and take action, like making a purchase or signing up for a newsletter.

And then there’s the business growth angle. As you think about expanding into new regions, internationalization becomes essential. You need to adapt the content to suit local preferences, whether that’s adjusting the tone, formatting dates and currencies, or even tweaking calls-to-action to align with cultural norms.

When you’re setting up internationalization in Storyblok, you have three main options to choose from: field-level translation, folder-level translation, and space-level translation. Each one fits different needs, depending on the complexity of my project and how much localization is required.

Storyblok offers three main approaches to internationalization: field-level translation, folder-level translation, and space-level translation. Each suits different project needs, depending on the complexity and localization requirements. Here’s a breakdown of what each approach involves and when to use it.

1. Field-Level Translation works well for content with a similar structure across languages. For example, managing a blog or e-commerce site where the layout remains consistent but the text changes, like product descriptions in English, Spanish, or French, makes this approach ideal. A single story in Storyblok can include translations for specific fields, keeping everything organized in one place.
2. Folder-Level Translation is suitable when more flexibility is needed for highly localized content. For content tailored to different regions where not just the language but also the structure or components differ—like a marketing campaign customized for the US versus Europe—this approach fits best. Separate folders for each language or region can be created in Storyblok’s Content section, allowing complete customization of the content structure.
3. Space-Level Translation suits complex projects with dedicated teams or platforms. For a global enterprise with distinct regional sites—like separate platforms for North America, Asia, and Europe—this approach provides the most autonomy. Each region gets its own Storyblok space, which can be customized independently. To maintain consistency, Storyblok’s CLI or Management API can be used to share components or schemas across spaces.

Comparison Table

Here’s my updated comparison table, incorporating practical considerations and examples to make it more actionable:

These approaches aren’t mutually exclusive. For example, folder-level translation can be combined with field-level translation to offer multiple languages within region-specific content, providing flexibility to meet diverse project needs.

When fetching content, you can use the Content Delivery API to pull specific language versions. For field-level translation, add the language parameter, like this:

Storyblok.get('cdn/stories/home', {
  language: 'es',
  version: 'published',
})
  .then(response => console.log(response))
  .catch(error => console.log(error));

For folder-level translation, you can use the starts_with parameter to retrieve content from a specific folder:

Storyblok.get('cdn/stories/home', {
  starts_with: 'es',
  version: 'published',
})
  .then(response => console.log(response))
  .catch(error => console.log(error));

For space-level translation, configure separate API calls for each space, ensuring to access the right content for each region. This makes it easy to integrate Storyblok with my front-end framework, like Next.js or Nuxt.js, to deliver localized content dynamically.

Field-level translation in Storyblok is my preferred choice for managing translations when content has a consistent structure across languages. It’s ideal for projects like blogs or online stores where the layout stays the same, but text elements—such as titles, descriptions, or calls-to-action—need to vary by language.

Setup and Configuration

1. To set up field-level translation, start by navigating to Settings > Internationalization in the Storyblok space. This is where languages are defined. For example, to target English, German, and Japanese audiences, add those languages here.
2. After saving, Storyblok prepares the space to handle translations for these languages.
3. Next, go to the Block Library to enable translatable fields. This involves editing the schemas of content blocks. For instance, in a “Product” component with fields like “name” and “description,” mark those as translatable by checking the “Translatable” option in the field settings.
4. Note that only certain field types—like text, textarea, or markdown—can be translated, while others, such as blocks or asset fields, cannot. This limitation influences content structure design, so plan ahead to ensure flexibility.

Using Translatable Fields

AI Translation and Third-Party Services

When a project needs more than translated text, such as different layouts or components for different regions, folder-level translation is my go-to solution. It’s perfect for highly localized content, like a marketing site with unique designs for the US versus Japan.

Creating Language-Specific Folders

1. In the Content section of Storyblok, create separate folders for each language or region, such as /en for English, /de for German, and /jp for Japanese. Each folder can hold its own stories, allowing customization of both text and structure. For example, the English folder might include a “Featured Products” section, while the Japanese folder uses a “Customer Testimonials” block to suit that market.
2. This approach offers full control over localization but requires managing more content.
3. To stay organized, establish naming conventions (e.g., “home-en” versus “home-jp”) and document the folder structure for the team.

Using the Dimensions App

1. The Dimensions app enhances folder-level translation by linking related stories across folders.
2. After installing it from the Storyblok App Directory, relationships can be defined between, say, the English and German versions of a blog post.
3. In the editor, use the app’s interface to select a story in one folder (e.g., /en/blog-post) and link it to its counterpart in another (e.g., /de/blog-post). This connection simplifies navigation between versions and update propagation.
4. This can also be combined with field-level translation within a folder. For example, the /en folder might offer English and Canadian English variants for a single story, using translatable fields alongside the folder structure.

For large-scale projects—like a global brand with separate platforms for different regions—space-level translation is the way I approach things. It provides each team or region with its own Storyblok space for complete independence.

Managing Multiple Spaces

1. Creating multiple spaces involves setting up new ones in the Storyblok account—one for North America, another for Asia, and so on.
2. Each space operates as a standalone environment with its own content, components, and settings. This is useful when collaboration between regions is minimal or when teams need full autonomy. For instance, the European team can adjust their space’s design system without impacting the North American setup.
3. The challenge is that managing multiple spaces can become complex, especially for updates requiring consistency across regions.

Sharing Components Across Spaces

1. To ensure consistency across spaces, Storyblok’s CLI and Management API can be used. For example, if a “Header” component is created in the North American space and needs to be reused, run a command like storyblok pull-components --space <space-id> to export the schema, then storyblok push-components --space <target-space-id> to import it into another space.
2. The Management API enables similar functionality programmatically, allowing scripts to sync components or schemas across all spaces.
3. This method requires technical knowledge but is effective for large projects. Maintaining a shared repository of components can streamline the process.

When I need robust translation workflows for my Storyblok projects, third-party integrations are a fantastic option. They offer advanced features like translation memory and collaborative tools, complementing Storyblok’s built-in capabilities.

DeepL Integration

In the Visual Editor, select a translatable field, choose the target language, and use the DeepL option to generate translations. These can be reviewed and edited before saving. DeepL’s strength lies in its accuracy for complex phrases, but it requires an API subscription, which may add costs depending on translation volume.

For example, translating a blog post’s title and body from English to French involves selecting the fields, running DeepL’s translation, and verifying the output for tone and context. This integration streamlines the process but benefits from manual oversight to ensure cultural accuracy.

Lokalise Integration

After setup, connect the app using Lokalise API credentials. Create a project in Lokalise, then map Storyblok content fields to Lokalise keys. Content can be exported to Lokalise for translation, where features like translation memory and glossaries ensure consistency. Once translations are complete, import them back into Storyblok via the app.

For instance, a product page with multiple fields can be exported to Lokalise, translated by a team, and synced back to Storyblok, maintaining consistent terminology across languages. Lokalise’s collaborative features are ideal for projects with multiple translators, though setup time and costs should be considered.

Crowdin Integration

Storyblok content is exported to Crowdin, where translators work on it, leveraging tools like translation memory or machine translation integrations. After completion, translations are imported back into Storyblok. For example, a global e-commerce site can use Crowdin to manage translations for product descriptions across 10 languages, with daily syncs to keep content updated.

Crowdin’s strength is its scalability for large teams, but it requires careful configuration to avoid sync issues. Testing in a staging environment before publishing is recommended.

Other Services

In addition to DeepL, Lokalise, and Crowdin, Storyblok supports integrations with services like Localazy and Smartling. Localazy simplifies translation with automated workflows and a user-friendly interface, ideal for smaller projects.

To make multilingual content discoverable, SEO is critical. Storyblok’s tools help optimize content for search engines, ensuring it reaches the right audiences.

Translatable Slugs

For instance, an e-commerce site might use /products for English and /produkte for German, making navigation intuitive. Ensure slugs are consistent and avoid special characters to maintain SEO compatibility.

Hreflang Tags and Sitemaps

Hreflang tags signal to search engines which language or regional version of a page to display. In Storyblok, fetch content for each language using the Content Delivery API’s language parameter, then generate hreflang tags in the frontend. For example, a Next.js site might include:

<link rel="alternate" hreflang="en" href="https://example.com/en/about" />

<link rel="alternate" hreflang="es" href="https://example.com/es/sobre" />

Multilingual sitemaps are also essential. Create a sitemap for each language, listing all translated URLs, and submit them to search engines via tools like Google Search Console. Storyblok’s API can be used to generate sitemaps dynamically, ensuring all language variants are included.

Localization goes beyond translation to include cultural nuances, ensuring content resonates with local audiences.

Adapting Date and Currency Formats

Translatable fields in Storyblok can handle regional preferences like date formats (e.g., MM/DD/YYYY for the US, DD/MM/YYYY for Europe) and currencies (e.g., USD, EUR). Configure separate fields for these elements in the Block Library. For example, a product component might include a “price” field with currency-specific values, displayed based on the user’s language or region.

This approach ensures content feels familiar to users. For instance, a European user sees prices in euros with a comma decimal separator, while a US user sees dollars with a period.

Region-Specific Content

Managing region-specific content, like promotions or legal notices, is straightforward with Storyblok. Use folder-level or space-level translation to create tailored content. For example, a US folder might include a “Black Friday Sale” story, while a European folder features a “GDPR Compliance” notice. Translatable fields within these structures can further refine content, such as localized calls-to-action.

Regular collaboration with local teams ensures accuracy. For instance, a Japanese campaign might prioritize formal language, while a Brazilian one uses a conversational tone.

When I think about making internationalization work smoothly in Storyblok, it’s all about setting up a strategy that aligns with my project’s goals. Whether I’m managing a small blog or a global enterprise site, following best practices helps me get the most out of Storyblok’s powerful tools.

Choosing the Right Approach

Selecting the appropriate internationalization approach—field-level, folder-level, or space-level translation—depends on the project’s requirements. Here’s how to decide:

• Field-Level Translation: This approach suits projects with consistent content structures across languages, such as blogs or e-commerce sites with uniform layouts. It’s efficient because translations are managed within a single story. For example, a product page with a “name” and “description” field can have translations for English, Spanish, and French without duplicating content. Choose this for small to medium-sized projects with minimal structural differences.
• Folder-Level Translation: Opt for this when content needs significant localization, including structural changes. For instance, a marketing site might require different layouts for the US and Japan, with unique components like banners or testimonials. Separate folders (e.g., /en, /jp) allow customization while keeping content organized. This is ideal for projects with moderate complexity and region-specific needs.
• Space-Level Translation: This is best for large-scale projects with dedicated teams or platforms, such as a global brand with distinct regional sites. Each region gets its own Storyblok space, offering full autonomy. For example, a North American space might focus on USD pricing, while an Asian space uses JPY and local promotions. Use this for complex projects requiring independent workflows.

To choose, consider the project’s size, team structure, and localization depth. Smaller teams with simple needs benefit from field-level translation’s simplicity, while larger organizations with diverse requirements may need folder-level or space-level approaches. Combining approaches, like using field-level within folder-level translation, can address hybrid needs, such as offering multiple languages within a region-specific folder.

Avoiding Common Pitfalls

Several common mistakes can derail internationalization efforts, but they can be avoided with careful planning:

• Inconsistent Language Handling: Failing to configure all translatable fields consistently can lead to missing translations. Ensure all relevant fields are marked as translatable in the Block Library and verify translations in the Visual Editor before publishing. For example, omitting a “call-to-action” field from translation settings could result in English text appearing on a German page.
• Neglecting SEO: Overlooking multilingual SEO can reduce content visibility. Implement hreflang tags for each language version and create language-specific sitemaps. For instance, a site with /en/about and /es/sobre pages should include <link rel="alternate" hreflang="es" href="/es/sobre" /> in the frontend. Submit sitemaps to search engines via Google Search Console to improve indexing.
• Overcomplicating Folder Structures: In folder-level translation, creating too many folders or inconsistent naming can complicate management. Use clear conventions, like /en/home and /de/home, and document the structure to streamline collaboration.
• Ignoring Cultural Nuances: Translating text without adapting to cultural preferences can alienate users. Use translatable fields for region-specific formats, such as DD/MM/YYYY for Europe or USD versus EUR for pricing. Collaborate with local teams to ensure content resonates.
• Not Testing Translations: Publishing without testing can lead to errors. Use Storyblok’s preview mode to review translations with native speakers, checking for accuracy and context. For example, test a French product description to ensure it uses the correct tone for the audience.

Closing Insights for Multilingual Content

Storyblok’s internationalization tools—field-level, folder-level, and space-level translation—offer flexible solutions for managing multilingual content. Field-level translation keeps things simple for consistent layouts, folder-level translation provides flexibility for localized structures, and space-level translation supports complex, autonomous projects.

By choosing the right approach, avoiding pitfalls like inconsistent translations or poor SEO, and optimizing workflows, global content strategies can be executed effectively in Storyblok CMS. Select the approach that aligns with the project’s scale and localization needs to deliver content that resonates with audiences worldwide.