Adding and updating locales in your Makerkit application

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 must 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 your bundle size.

For example, the translations for the authentication are placed in auth.json, while the ones used across every page are placed under common.json.

If you are unsure where to add some translations, simply add them to common.json.

Adding new languages

By default, Makerkit uses English for translating the website's text. All the files are stored in the files at /public/locales/en.

Adding a new language is very simple:

1. Translation Files: First, we need to create a new folder, such as /public/locales/es, and then copy over the files from the English version and start translating files.
2. Next.js i18n config: We need to also add a new language to the Next.js configuration at next-i18next.config.js. Simply add your new language's code to the locales array.

The configuration will look like the below:

const config = {
  i18n: {
    defaultLocale: DEFAULT_LOCALE,
    locales: [DEFAULT_LOCALE, 'es'],
  },
  fallbackLng: {
    default: [DEFAULT_LOCALE],
  },
  localePath: resolve('./public/locales'),
};

Adding new translation files

For example, let's assume you add a new namespace (e.g. 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' // <---
status: "published"
 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.

Setting the default Locale

To set the default locale, simply update the environment variable DEFAULT_LOCALE stored in .env.

So, open the .env file, and update the variable:

DEFAULT_LOCALE=de

Using the Language Switcher component

The Language switcher component will automatically retrieve and translate the languages listed in your configuration.

When the user changes language, it will update the URL to reflect the user's preferences and rerender the application with the selected language.

NB: The language selector is not added to the application by default; you will need to import it where you want to place it.

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 excellent if the translations in the specified JSON file are only added to a specific page.