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, you must add the route name to your route translations in app.i18n.cjs for each locale.

warning

If you don't add route translations for a new page, your application will fail to build with an error. Each file-based route must have a corresponding translation entry in app.i18n.cjs.

For example, if you create pages/settings.tsx, add to the ROUTE_TRANSLATIONS object in app.i18n.cjs:

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

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. Configure the locale in your app's next.config.js i18n settings
  4. Update app.i18n.cjs with the new locale in LOCALES and add translations to all routes in ROUTE_TRANSLATIONS