Overview
This document provides guidelines for adding a new locale to the Page Builder application. The example below uses German (de-DE).
The application uses next-intl with locale-prefixed Next.js routes.
1. Register the New Locale
Add the new locale to the following file:
packages/constants/src/i18n.ts
Example:
exportconstLOCALES = ["en-US","fr-FR", "de-DE"];
Keep the fallback locale as en-US unless the new locale is intended to become the application-wide fallback locale.
Default Locale Configuration
The application-wide default locale is also defined in the following files:
packages/constants/src/settings.ts packages/constants/src/app.ts
Update these files only if the application-wide default locale needs to be changed.
Note: Adding a locale to the LOCALES array makes the locale available to the application. The default locale configuration should only be modified when the new locale must become the application's primary fallback locale.
2. Routing Configuration
The routing configuration is located at:
apps/page-builder/src/i18n/routing.ts
It uses the LOCALES configuration automatically:
export const routing = defineRouting({
locales: LOCALES,
defaultLocale: FALLBACK.code,
});Therefore, no direct routing change is required after adding de-DE to the LOCALES array.
Locale-Based Routes
Locale-specific routes are available under:
apps/page-builder/src/app/[locale]/
Examples:
- /de-DE
- /de-DE/page-builder
- /de-DE/<slug>
Note: Once a new locale is added to the LOCALES configuration, locale-prefixed routes are automatically recognized by the routing system.
3. Add Translation Files
Create a new translation file for the locale:
apps/page-builder/messages/de-DE.json
Use the existing English translation file as the reference:
apps/page-builder/messages/en-US.json
Copy the same namespace and key structure from the English file and translate the required values.
Common Namespaces
- Common
- Product
- Layout
- Checkout
- Login
- Search
Translation Loading
Translations are loaded through:
apps/page-builder/src/i18n/request.ts
Example:
messages: (await import(`../../messages/${locale}.json`)).defaultEnsure that the translation file name matches the locale code exactly.
Example:
de-DE.json
Missing or invalid locales should continue to use the configured fallback locale (en-US).
Important: The locale code and translation file name must match exactly. Any missing or unsupported locale automatically falls back to the configured default locale.
4. Middleware Configuration
The middleware configuration is located at:
apps/page-builder/src/middleware.ts
The middleware uses both the routing configuration and the LOCALES array to determine whether a locale is supported.
After adding de-DE to the LOCALES configuration, URLs that begin with /de-DE are automatically recognized as valid locale routes.
Unsupported Locales
Unsupported hyphenated locales, such as:
/es-ES
are redirected to the configured fallback locale:
/en-US
In most cases, no middleware code changes are required when adding a new supported locale
Middleware Responsibilities
- Reading storeCode from the query string or referrer URL.
- Loading portal data using getPortalDataFromGlobalCache.
- Setting DEFAULT_LOCALE and NEXT_LOCALE cookies.
- Handling redirects for unsupported locales.
5. URL Format
Use the appropriate storeCode when testing locale-specific URLs.
Home Page
http://localhost:3000/de-DE?storeCode=<store-code>
Page Builder
http://localhost:3000/de-DE/page-builder?storeCode=<store-code>
Content Page
http://localhost:3000/de-DE/<slug>?storeCode=<store-code>
The storeCode should be preserved when navigating between locale-based pages to ensure consistent portal and locale behavior.
Validation: Verify that both the locale prefix and storeCode remain unchanged across page navigation, refreshes, and Page Builder operations.
6. HTML Language Attribute
The root layout is located at:
apps/page-builder/src/app/[locale]/layout.tsx
The current implementation contains:
<html lang="en-US" {...theme}>To support locale-specific HTML metadata, the lang attribute should reflect the active route locale.
Example:
<html lang="de-DE" {...theme}>Ideally, the lang value should be derived dynamically from the [locale] route parameter so that all supported locales automatically receive the correct language attribute.
This configuration is independent of translation loading and should be validated separately.
Best Practice: Dynamically setting the HTML lang attribute improves accessibility, browser language detection, search engine indexing, and overall localization support for all configured locales.