Localization

Manage localized content by editing from the content source or extending with Stackbit.

This a new feature. Implementation details are subject to rapid change. Please contact us for more information and to stay updated with the latest changes.

Requirements

This feature requires that content sources are managed via Content Source Interface, and is only available in the business and enterprise tiers.

Types of Localization

Stackbit supports two types of localization.

  • Object-level localization: Each document or object is associated with a single locale.
  • Field-level localization: A document or object may have multiple locales, as determined by the fields within that object.

Object vs Field Example

For example, consider a site that has a Post model with title and body fields, and serves content in both the fr (French) and de (German) locales.

If using object-level localization, there would be two documents of type Post, one for fr and another for de.

If using field-level localization, there would only be a single object, while title might be an object with properties fr and de, storing the string reference to the value in each locale.

How Stackbit handles localization for you project depends on a number of factors, including the content source(s) being used, the site's localization strategy, along with the provided Stackbit configuration.

Configuring Localization

Models or their fields need to set the localized property to true in the schema, and the content objects themselves to have a locale property assigned, where the value is the string reference to that field (e.g. de for German language content).

Overriding CSI Modules

In some cases, locale behavior may be provided by the CSI module. If not, the CSI module can be extended to provide the appropriate logic to its internal methods, and to apply the appropriate properties to the models and documents.

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
export default {
  contentSources: [
    new ContentfulContentSource({
      spaceId: process.env.CONTENTFUL_SPACE_ID,
      environment: process.env.CONTENTFUL_ENVIRONMENT,
      previewToken: process.env.CONTENTFUL_PREVIEW_TOKEN,
      accessToken: process.env.CONTENTFUL_MANAGEMENT_TOKEN,
    }),
  ],
  // Add `localized` property to localized models.
  mapModels({ models }) {
    return models.map((model) => {
      // `LOCALIZED_MODELS` is an array of model name strings.
      if (LOCALIZED_MODELS.includes(model.name)) {
        return { ...model, localized: true }
      }
      return model
    })
  },
  // Add `localized` field values to localized objects.
  mapDocuments({ documents }) {
    return documents.map((document) => {
      // `LOCALIZED_MODELS` is an array of model name strings.
      if (LOCALIZED_MODELS.includes(document.modelName)) {
        // `getDocumentLocale` returns the appropriate locale string for the document.
        const locale = getDocumentLocale(document)
        return { ...document, locale }
      }
      return document
    })
  },
  // Alternatively, use `models` to extend models in a more static way.
  models: {
    // ...
  },
}
Here's a more complete example using Contentful as the content source.

Access Control

Access to one or more locales can be controlled through your project settings.

When adding a member or a team to the project, they can be limited to a single locale or be given access to all locales (global). If nothing is selected in the restriction dropdown, the user will have full access to all locales (global).

Locale Access Control
Locale Access Control

See below for more information on locale modes (global vs specific).

Locale Modes

There are 2 modes for the locale switcher: global and locale. These modes are used to handle access control, along with the current editing context.

When in global mode:

  • Object-level: Users can view, create, and publish objects of all locales.
  • Field-specific: Objects are common across locales. Users can view, create, and publish all objects, but only the default locale fields are rendered to be edited. The rest of the locales, require users to go to a specific locale to edit them.

When in locale mode:

  • Object-level: Users can view, create, edit, and publish only content entries within the selected locale. Non-localized objects can be viewed but not edited from a specific locale.
  • Field-specific: Users can view, create, edit, and publish only fields of the content entry within the selected locale. Non-localized objects can be viewed but not edited from a specific locale.

The next section covers governance on field-level localization. More on editing below.

Governance for Field Localization

While you can control editing within a specific locale, full governance and publishing control is not available for field-level localization.

Localization Method
Governance
Publishing
Object-Level
✔️
✔️
Field-Level

This is because editors will have access to view non-localized content. And there is no way to be able to publish only values within a specific locale for a specific field. More on both editing and publishing below.

Editing Localized Content

Managing localized content is done within the context of the current locale mode. This is controlled through the locale switcher, and it affects how objects are viewed, created, edited, published, and stored as presets.

Locale Switcher

The current locale can be set via the locale switcher, found in the top bar controls within the visual editor.

Localization - Choose Locale
Localization - Choose Locale

Making a selection here changes the editing context for all content in the site.

Default Locale

There is always a defaultLocale (most commonly en-US, but it can be changed). The default locale is the one immediately below Global in the locale switcher dropdown.

Creating New Objects

Creating objects in Stackbit differs depending on the chosen localization strategy:

When using object-level localization in global mode, there will be multiple tabs. The editor must fill out the required fields in each of the selected locales before being able to create the object. This results in multiple objects, one per selected locale.

New Object in Global Mode
New Object in Global Mode

When using object-level localization in locale mode, it is only possible to create a new object in that locale (set via the locale switcher).

New Object within Specific Locale
New Object within Specific Locale

When using field-specific localization, the editor must fill out values for the default locale (required to build the object's base fields), along with fields that are required and localized in other tabs.

This action creates only one object, while additional selected locales will be added as additional values to the existing object. To avoid editors accidentally generating content in multiple locales, creating objects with field-specific localization is only possible within global mode.

New Object in Global Mode using Field-Specific Localization
New Object in Global Mode using Field-Specific Localization

Editing Existing Objects

The editing experience differs depending on the localization strategy being used.

  • Object-level: In global mode, all objects are shown and editable. In locale mode, only objects of the selected locale can be edited, though objects without a locale will still be shown.
  • Field-specific: Locale flags will show up next to objects and fields that are localized. In global mode, only fields of the default language are accessible. In locale mode, the fields of the selected locale will be shown.
Localized Fields
Localized Fields

Localized Presets

Localized presets work differently depending on the localization strategy and mode being used:

In both object-level and field-specific, when in a specific locale, presets will be saved and visible only in the current locale as well as global mode. When in global mode, new presets will be visible to all other locales and can be used by all locales.

In the case of field-specific localization, the same (and unique) preset values will be used in any locale. Presets cannot store different values for different locales. Instead, save multiple templates, one for each desired locale.

Publishing Localized Content

In a specific locale, the publish dropdown will only show objects that are localized to the currently-selected locale, along with objects that have localized fields. Publishing can not be focused on a specific localized field value.

Users with access to the Global view will have visibility of changes and be able to publish all content.

Custom Visual Editing Behavior

You can customize how your website preview responds to localization changes in the visual editor using client-side JavaScript.

setLocale

Enables you to change the current locale, which will update the locale switcher.

  • 1
window.stackbit.setLocale(locale)

See the reference for details.

stackbitLocaleChanged

Listen for an editor to interact with the locale switcher and change the current locale.

  • 1
  • 2
  • 3
  • 4
window.addEventListener('stackbitLocaleChanged', (event) => {
  const locale = event.detail.locale
  // Add custom behavior ...
})

This may be useful for redirecting the current page to a version with the newly-selected locale. See the reference for details.