Translations and Locales

Much of the MakerKit's codebase uses translations using the package `next-i18next':

  • this package allows you to create multi-language apps effortlessly
  • it also helps easily renaming the Makerkit's entities according to your preferences: for example, renaming "organizations" to another entity such as "team" or "workspace"
  • in a way, it helps write cleaner HTML

To add or update the default strings you have to use the locale files at public/locales/{lang}.json. For example, all the locale files for the English language are placed under public/locales/en.

The locales are split by functionality, page or entity: as your application grows, you may not want to load every JSON file to reduce the size of your bundle.

For example, the translations for the authentication are placed in auth.json, while the ones that are used across every page are placed under common.json. If you are not sure where to add some translations, simply add them to common.json.

To simplify things, the MakerKit's starter uses by default all the available JSON files, and we recommend doing so until you have too many files.

Adding a new translation file

To add a new translation file, simply add a JSON file at public/locales/en/{filename}.json. Then, open the file src/lib/props/with-translation-props.ts withTranslationProps and add the namespace to DEFAULT_OPTIONS.

For example, let's assume you add a new namespace (eg. a JSON file) named editor.json. Now, to automatically add the translations of this file, we will add it to the DEFAULT_OPTIONS variable:

const DEFAULT_OPTIONS: Options = {
  locale: DEFAULT_LOCALE,
  localeNamespaces: [
    'common',
    'auth',
    'organization',
    'profile',
    'subscription',
    'editor' // <--- HERE IT IS
  ],
};

If you want to simplify things, simply merge all the files into one; the only downside is that lazy-loading translation files will not be possible.

Lazy Loading Locale files

Let's assume your editor.json file is only loaded in your EditorPage component; so it can make sense to only load translations on that page. To do so, we can use withAppProps:

export default function EditorPage() {
  return <></>;
}

export function getServerSideProps() {
  return withAppProps({
    localeNamespaces: ['editor']
  });
}

The editor namespace will be added to the default ones specified in DEFAULT_OPTIONS. This approach is great if the translations in the specified JSON file are only added to a specific page.


Stay informed with our latest resources for building a SaaS

Subscribe to our newsletter to receive updatesor