1. Register the New Locale
Add the new locale to the following file:
packages/constants/src/i18n.ts
Example:
export const LOCALES = ["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.
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>
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
CommonProductLayoutCheckoutLoginSearch
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).
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
storeCodefrom the query string or referrer URL. - Loading portal data using
getPortalDataFromGlobalCache. - Setting
DEFAULT_LOCALEandNEXT_LOCALEcookies. - 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.
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.
lang attribute improves accessibility, browser language detection, search engine indexing, and overall localization support for all configured locales.