I18n

The Admin Panel is translated in over 30 languages and counting. With I18n, editors can navigate the interface and read API error messages in their preferred language. This is similar to Localization, but instead of managing translations for the data itself, you are managing translations for your application’s interface. By default, FrogBot comes preinstalled with English, but you can easily load other languages into your own application. Languages are automatically detected based on the request. If no language is detected, or if the user’s language is not yet supported by your application, English will be chosen. To add I18n to your project, you first need to install the @frogbotcms/translations package:

pnpm install @frogbotcms/translations

Once installed, it can be configured using the i18n key in your FrogBot Config:

import { buildConfig } from 'frogbot'

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

Note: If there is a language that FrogBot does not yet support, we accept code contributions.

Config Options

You can easily customize and override any of the i18n settings that FrogBot provides by default. FrogBot will use your custom options and merge them in with its own.

import { buildConfig } from 'frogbot'

export default buildConfig({
  // ...
  i18n: {
    fallbackLanguage: 'en', // default
  },
  // ...
})

The following options are available:

Option	Type	Default	Description
`fallbackLanguage`	`AcceptedLanguages`	`'en'`	Language used when the user’s preferred language isn’t supported. If it isn’t one of `supportedLanguages`, the first supported language is used.
`supportedLanguages`	`Partial<Record<AcceptedLanguages, Language>>`	`{ en }`	Languages the admin panel offers, keyed by language code. Each value is a language object with its translations. More details.
`translations`	`Partial<Record<AcceptedLanguages, object>>`	—	Translation overrides and additions, keyed by language code. They are merged into the built-in strings. More details.

Adding Languages

You can easily add new languages to your FrogBot app by providing the translations for the new language. FrogBot maintains a number of built-in translations that can be imported from @frogbotcms/translations, but you can also provide your own Custom Translations to support any language. To add a new language, use the i18n.supportedLanguages key in your FrogBot Config:

import { buildConfig } from 'frogbot'
import { en } from '@frogbotcms/translations/languages/en'
import { de } from '@frogbotcms/translations/languages/de'

export default buildConfig({
  // ...
  i18n: {
    supportedLanguages: { en, de },
  },
  // ...
})

Tip: It’s best to only support the languages that you need so that the bundled JavaScript is kept to a minimum for your project.

Custom Translations

You can customize FrogBot’s built-in translations either by extending existing languages or by adding new languages entirely. This can be done by injecting new translation strings into existing languages, or by providing an entirely new language keys altogether. To add Custom Translations, use the i18n.translations key in your FrogBot Config:

import { buildConfig } from 'frogbot'

export default buildConfig({
  //...
  i18n: {
    translations: {
      en: {
        custom: {
          // namespace can be anything you want
          key1: 'Translation with {{variable}}', // translation
        },
        // override existing translation keys
        general: {
          dashboard: 'Home',
        },
      },
    },
  },
  //...
})

Project Translations

While FrogBot’s built-in features come fully translated, you may also want to translate parts of your own project. This is possible in Collections, including labels and groups, field labels, descriptions, and input placeholder text. To do this, provide the translations wherever applicable, keyed to the language code:

import type { CollectionConfig } from 'frogbot'

export const Articles: CollectionConfig = {
  slug: 'articles',
  labels: {
    singular: {
      en: 'Article',
      es: 'Artículo',
    },
    plural: {
      en: 'Articles',
      es: 'Artículos',
    },
  },
  admin: {
    group: {
      en: 'Content',
      es: 'Contenido',
    },
  },
  fields: [
    {
      name: 'title',
      type: 'text',
      label: {
        en: 'Title',
        es: 'Título',
      },
      admin: {
        placeholder: {
          en: 'Enter title',
          es: 'Introduce el título',
        },
      },
    },
  ],
}

Changing Languages

Users can change their preferred language in their account settings or by otherwise manipulating their User Preferences.

Node.js#node

FrogBot’s backend sets the language on incoming requests before they are handled. This allows backend validation to return error messages in the user’s own language or system generated emails to be sent using the correct translation. You can make HTTP requests with the accept-language header and FrogBot will use that language. Anywhere in your FrogBot app that you have access to the req object, you can access FrogBot’s extensive internationalization features assigned to req.i18n. To access text translations you can use req.t('namespace:key').

TypeScript

In order to use Custom Translations in your project, you need to provide the types for the translations. Here we create a shareable translations object. We will import this in both our custom components and in our FrogBot config. In this example we show how to extend English, but you can do the same for any language you want.

// <rootDir>/custom-translations.ts

import { enTranslations } from '@frogbotcms/translations/languages/en'
import type { NestedKeysStripped } from '@frogbotcms/translations'

export const customTranslations = {
  en: {
    general: {
      myCustomKey: 'My custom english translation',
    },
    fields: {
      addLabel: 'Add!',
    },
  },
}

export type CustomTranslationsObject = typeof customTranslations.en &
  typeof enTranslations
export type CustomTranslationsKeys =
  NestedKeysStripped<CustomTranslationsObject>

Import the shared translations object into our FrogBot config so they are available for use:

// <rootDir>/frogbot.config.ts

import { buildConfig } from 'frogbot'

import { customTranslations } from './custom-translations'

export default buildConfig({
  //...
  i18n: {
    translations: customTranslations,
  },
  //...
})

Import the shared translation types to use in your custom component:

// <rootDir>/components/MyComponent.tsx

'use client'
import type React from 'react'
import { useTranslation } from '@frogbotcms/ui'

import type {
  CustomTranslationsObject,
  CustomTranslationsKeys,
} from '../custom-translations'

export const MyComponent: React.FC = () => {
  const { i18n, t } = useTranslation<
    CustomTranslationsObject,
    CustomTranslationsKeys
  >() // These generics merge your custom translations with the default client translations

  return t('general:myCustomKey')
}

Additionally, FrogBot exposes the t function in various places, for example in labels. Here is how you would type those:

// <rootDir>/fields/myField.ts

import type { TFunction } from '@frogbotcms/translations'
import type { Field } from 'frogbot'

import { CustomTranslationsKeys } from '../custom-translations'

const field: Field = {
  name: 'myField',
  type: 'text',
  label: ({ t: defaultT }) => {
    const t = defaultT as TFunction<CustomTranslationsKeys>
    return t('fields:addLabel')
  },
}

Start here

Basics

Managing Data

Features

Ecosystem

Deployment

Config Options

Adding Languages

Custom Translations

Project Translations

Changing Languages

Node.js#node

TypeScript

​Config Options

​Adding Languages

​Custom Translations

​Project Translations

​Changing Languages

​Node.js#node

​TypeScript

Config Options

Adding Languages

Custom Translations

Project Translations

Changing Languages

Node.js#node

TypeScript