Skip to main content

Adding a new translation

Blueprint uses next-i18next for internationalization. For an overview of how i18n works in Blueprint, see the i18n overview.

Translation file structure​

Translation files are organized by locale and namespace:

apps/foundation/src/translations/locales/
  ├── en/
  │   ├── common.json
  │   ├── homepage.json
  │   └── ...
  ├── fr/
  │   ├── common.json
  │   └── ...
  └── de/
      └── ...

Adding a translation key​

Add your translation to the appropriate JSON file for each locale. Use nested objects for organization:

{
  "greeting": "Hello",
  "user": {
    "welcome": "Welcome back",
    "logout": "Log out"
  }
}

Note: After adding or modifying translation files, you may need to restart your dev server for the changes to take effect.

Using translations in code​

Import useTranslation from next-i18next and specify the namespace:

import { useTranslation } from "next-i18next";

export const MyComponent = () => {
  const { t } = useTranslation("common");

  return (
    <div>
      <h1>{t("greeting")}</h1>
      <p>{t("user.welcome")}</p>
    </div>
  );
};

Route translations​

Blueprint's route generation also supports internationalization. When you create a new page using Next.js file-based routing, add each new static path segment to ROUTE_TRANSLATIONS in src/app.i18n.json.

warning

If a static path segment or one of its locale translations is missing, your application will fail to build. Dynamic path segments such as [accountNumber] don't need translation entries.

For example, if you create pages/settings.tsx, add this entry to ROUTE_TRANSLATIONS:

{
  "settings": {
    "de": "einstellungen",
    "en": "settings",
    "fr": "parametres"
  }
}

For more details on route translations, see the i18n overview.

Adding a new locale​

To add support for a new language:

  1. Create a new locale directory in src/translations/locales/ (e.g., src/translations/locales/es/)
  2. Add translation JSON files for all existing namespaces
  3. Add the locale to LOCALES in src/app.i18n.json
  4. Import its date-fns locale and add it to appConfig.i18n.dateLocales in src/app.config.ts
  5. Add the locale translation to every entry in ROUTE_TRANSLATIONS