Localization

Localization is one of the most important features of a modern CMS. It allows you to manage content in multiple languages, then serve it to your users based on their requested language. This is similar to I18n, but instead of managing translations for your application’s interface, you are managing translations for the data itself. With Localization, you can begin to serve personalized content to your users based on their specific language preferences, such as a multilingual website or multi-site application. There are no limits to the number of locales you can add to your FrogBot project. To configure Localization, use the localization key in your FrogBot Config:

import { buildConfig } from 'frogbot'

export default buildConfig({
  // ...
  localization: {
    // ...
  },
})

Config Options

Add the localization property to your FrogBot Config to enable Localization project-wide. You’ll need to provide a list of all locales that you’d like to support as well as set a few other options. To configure locales, use the localization.locales property in your FrogBot Config:

import { buildConfig } from 'frogbot'

export default buildConfig({
  // ...
  localization: {
    locales: ['en', 'es', 'de'], // required
    defaultLocale: 'en', // required
  },
})

You can also define locales using full configuration objects:

import { buildConfig } from 'frogbot'

export default buildConfig({
  collections: [
    // collections go here
  ],
  localization: {
    locales: [
      {
        label: 'English',
        code: 'en',
      },
      {
        label: 'Arabic',
        code: 'ar',
        // opt-in to setting default text-alignment on Input fields to rtl (right-to-left)
        // when current locale is rtl
        rtl: true,
      },
    ],
    defaultLocale: 'en', // required
    fallback: true, // defaults to true
  },
})

Tip: Localization works very well alongside I18n.

The following options are available:

Option	Type	Default	Description
`locales`	`(string \| Locale)[]`	Required	Every locale you support, as codes or locale objects. More details.
`defaultLocale`	`string`	Required	One of the locale codes. Documents are read and written in this locale when a request doesn’t set `locale`.
`fallback`	`boolean`	`true`	When a localized field has no value in the requested locale, returns the value from the fallback locale instead. When `false`, the value stays empty unless the request sets `fallbackLocale`.
`filterAvailableLocales`	`({ locales, req }) => Locale[] \| Promise<Locale[]>`	—	Returns the locales shown in the admin panel’s locale selector. `req` is the current `FrogBotRequest`, with `req.frogbot`. More details.

Locales

The locales array is a list of all the languages that you would like to support. This can be strings for each language code, or full configuration objects for more advanced options. The locale codes do not need to be in any specific format. It’s up to you to define how to represent your locales. Common patterns are to use two-letter ISO 639 language codes or four-letter language and country codes (ISO 3166‑1) such as en-US, en-UK, es-MX, etc.

Locale Object

Option	Type	Default	Description
`code`	`string`	Required	Unique code that identifies the locale in `locale` and `fallbackLocale` arguments.
`label`	`string \| Record<string, string>`	Required	Name shown in the locale selector, or an object of names keyed by admin language.
`rtl`	`boolean`	`false`	Shows text inputs right-to-left while this locale is selected.
`fallbackLocale`	`string \| string[]`	`defaultLocale`	Locale, or ordered locales, to read from when a field has no value in this locale.

Filter Available Options

In some projects you may want to filter the available locales shown in the admin UI selector. You can do this by providing a filterAvailableLocales function in your FrogBot Config. This is called on the server side and is passed the array of locales and req, the current FrogBotRequest with req.frogbot. This means that you can determine what locales are visible in the localizer selection menu at the top of the admin panel. You could do this per user, or implement a function that scopes these to tenants and more. Here is an example using request headers in a multi-tenant application:

// ... rest of FrogBot config
localization: {
  defaultLocale: 'en',
  locales: ['en', 'es'],
  filterAvailableLocales: async ({ req, locales }) => {
    if (getTenantFromCookie(req.headers, 'text')) {
      const fullTenant = await req.frogbot.findByID({
        id: getTenantFromCookie(req.headers, 'text') as string,
        collection: 'tenants',
        overrideAccess: true,
        req,
      })
      if (fullTenant && fullTenant.supportedLocales?.length) {
        return locales.filter((locale) => {
          return fullTenant.supportedLocales?.includes(locale.code as 'en' | 'es')
        })
      }
    }
    return locales
  },
}

Since the filtering happens at the root level of the application and its result is not calculated every time you navigate to a new page, you may want to call router.refresh in a custom component that watches when values that affect the result change. In the example above, you would want to do this when supportedLocales changes on the tenant document.

Field Localization

FrogBot Localization works on a field level—not a document level. In addition to configuring the base FrogBot Config to support Localization, you need to specify each field that you would like to localize. Here is an example of how to enable Localization for a field:

{
  name: 'title',
  type: 'text',
  localized: true,
}

With the above configuration, the title field will now be saved in the database as an object of all locales instead of a single string. All field types with a name property support the localized property—even the more complex field types like arrays and blocks.

Note: Enabling Localization for field types that support nested fields will automatically create localized “sets” of all fields contained within the field. For example, if you have a page layout using a blocks field type, you have the choice of either localizing the full layout, by enabling Localization on the top-level blocks field, or only certain fields within the layout.

Important: When converting an existing field to or from localized: true the data structure in the document will change for this field and so existing data for this field will be lost. Before changing the Localization setting on fields with existing data, you may need to consider a field migration strategy.

Status Localization

When Localization is enabled and a collection has drafts enabled and at least one localized field, FrogBot localizes the _status field. Publication status is then tracked per locale, so you can publish in English while keeping Spanish as a draft. When the status field is localized, it is stored as an object keyed by locale:

status: {
  en: 'published',
  es: 'draft',
  de: 'published',
}

If _status isn’t localized, the status field remains a single string ('draft' or 'published') representing document status across all locales.

Publishing and unpublishing per locale

When the _status field is localized, publishing and unpublishing are scoped to a single locale by default. The locale being acted on is the one provided to the operation (via the locale parameter, or the request locale). This means publishing in one locale leaves the other locales’ statuses untouched.

// Publishes ONLY the Spanish status; English, German, etc. are unchanged
await frogbot.update({
  collection: 'posts',
  overrideAccess: true,
  id,
  locale: 'es',
  data: { _status: 'published' },
})

To publish or unpublish every locale at once, use publishAllLocales or unpublishAllLocales. These set the status for all locales the user has access to, regardless of the active locale:

// Publishes every locale
await frogbot.update({
  collection: 'posts',
  overrideAccess: true,
  id,
  publishAllLocales: true,
  data: { _status: 'published' },
})

// Unpublishes every locale
await frogbot.update({
  collection: 'posts',
  overrideAccess: true,
  id,
  unpublishAllLocales: true,
  data: { _status: 'draft' },
})

Passing locale: 'all' together with _status: 'published' also publishes every locale, and is equivalent to publishAllLocales: true.

When the _status field is not localized, publishing and unpublishing always apply to the whole document, and publishAllLocales / unpublishAllLocales have no effect.

The same parameters are available through the REST and Local APIs.

Retrieving Localized Docs

When retrieving documents, you can specify which locale you’d like to receive as well as which fallback locale should be used.

REST API

REST API locale functionality relies on URL query parameters. ?locale= Specify your desired locale by providing the locale query parameter directly in the endpoint URL. ?fallback-locale= Specify fallback locale to be used by providing the fallback-locale query parameter. This can be provided as either a valid locale as provided to your base FrogBot Config, or 'null', 'false', or 'none' to disable falling back. Example:

fetch('https://localhost:3000/api/pages?locale=es&fallback-locale=none');

GraphQL API

In the GraphQL API, you can specify locale and fallbackLocale args to all relevant queries and mutations. The locale arg will only accept valid locales, but locales will be formatted automatically as valid GraphQL enum values (dashes or special characters will be converted to underscores, spaces will be removed, etc.). If you are curious to see how locales are auto-formatted, you can use the GraphQL playground. The fallbackLocale arg will accept valid locales, an array of locales, as well as none to disable falling back. Example:

query {
  Posts(locale: de, fallbackLocale: none) {
    docs {
      title
    }
  }
}

In GraphQL, specifying the locale at the top level of a query will automatically apply it throughout all nested relationship fields. You can override this behavior by re-specifying locale arguments in nested related document queries.

Local API

You can specify locale as well as fallbackLocale within the Local API as well as properties on the options argument. The locale property will accept any valid locale, and the fallbackLocale property will accept any valid locale, array of locales, as well as 'null', 'false', false, and 'none'. Example:

const posts = await frogbot.find({
  collection: 'posts',
  overrideAccess: true,
  locale: 'es',
  fallbackLocale: false,
})

Tip: The REST and Local APIs can return all Localization data in one request by passing ‘all’ or ’*’ as the locale parameter. The response will be structured so that field values come back as the full objects keyed for each locale instead of the single, translated value.

Start here

Basics

Managing Data

Features

Ecosystem

Deployment

Config Options

Locales

Locale Object

Filter Available Options

Field Localization

Status Localization

Publishing and unpublishing per locale

Retrieving Localized Docs

REST API

GraphQL API

Local API

​Config Options

​Locales

​Locale Object

​Filter Available Options

​Field Localization

​Status Localization

​Publishing and unpublishing per locale

​Retrieving Localized Docs

​REST API

​GraphQL API

​Local API

Config Options

Locales

Locale Object

Filter Available Options

Field Localization

Status Localization

Publishing and unpublishing per locale

Retrieving Localized Docs

REST API

GraphQL API

Local API