Cookie-based Next-Intl Setup
Relevant source files
The following files were used as context for generating this wiki page:
The cookie-based internationalization (i18n) setup in this project enables persistent language selection across user sessions without relying on URL prefixes. By utilizing next-intl in conjunction with Next.js Server Actions and Middleware-like request configurations, the system stores the user's preferred locale in a dedicated cookie named NEXT_LOCALE.
This architecture allows the application to serve localized content dynamically on the server-side while providing a seamless client-side experience for switching languages. The setup supports both Left-to-Right (LTR) and Right-to-Left (RTL) layouts, specifically targeting English and Persian locales.
Core Configuration
The i18n system is initialized through a plugin in the Next.js configuration and a central configuration file that defines the supported languages.
| Option | Value | Description |
|---|---|---|
locales | ["en", "fa"] | Supported language codes. |
defaultLocale | "en" | Fallback language if no cookie is set. |
COOKIE_NAME | "NEXT_LOCALE" | The key used to store the locale in the browser. |
Sources: i18n/config.ts:3-5, i18n/locale.ts:7
Next.js Integration
The project integrates next-intl using a higher-order configuration in the next.config.ts file. This ensures that the i18n runtime is available throughout the Next.js build and request pipeline.
import type { NextConfig } from "next";
import createNextIntlPlugin from "next-intl/plugin";
const nextConfig: NextConfig = {};
const withNextIntl = createNextIntlPlugin();
export default withNextIntl(nextConfig);
Sources: next.config.ts:1-7
Data Flow and Persistence
The system relies on Server Actions to modify the locale cookie and next-intl request handlers to retrieve it. This flow ensures that the locale is synchronized between the client's browser and the server's rendering logic.
Sequence: Changing the Locale
When a user selects a different language via the UI, a transition is started to update the cookie and refresh the page data.
The MenuBar component handles the user interaction by calling setUserLocale and then triggering a router refresh to apply changes immediately.
Sources: features/desktop/components/MenuBar.tsx:28-33, i18n/locale.ts:14-16
Server-Side Retrieval
The i18n/request.ts file acts as the configuration provider for every request. It retrieves the locale (defaulting to the configuration if unavailable) and loads the corresponding translation JSON files from the messages/ directory.
Sources: i18n/request.ts:6-12
Locale Management Logic
The management of the locale is abstracted into two primary server-side functions located in i18n/locale.ts.
getUserLocale()
This asynchronous function attempts to read the NEXT_LOCALE cookie. It validates the value against the allowed locales array using hasLocale. If the cookie is missing or invalid, it returns the defaultLocale.
Sources: i18n/locale.ts:9-12
setUserLocale(locale: Locale)
This Server Action persists the chosen locale to the client's browser by setting the NEXT_LOCALE cookie.
Sources: i18n/locale.ts:14-16
Layout and Directionality
The root layout utilizes the retrieved locale to set the lang attribute and the dir (direction) attribute on the <html> element. This is critical for supporting the Persian (fa) locale, which requires Right-to-Left (RTL) rendering.
The layout logic determines the directionality as follows:
- English (en):
dir="ltr" - Persian (fa):
dir="rtl"
Sources: app/layout.tsx:23-25
UI Implementation
The MenuBar component provides the primary interface for language switching. It uses a standard HTML <select> element populated with the supported locales.
Implementation Details
- Current Locale Detection: Uses the
useLocale()hook fromnext-intl. - Translation: Uses the
useTranslations("menu")hook to localize option labels (e.g., "English", "Persian"). - State Transition: Wraps the locale change in
useTransition()to maintain UI responsiveness while the server action processes.
Sources: features/desktop/components/MenuBar.tsx:18-53
Summary
The cookie-based next-intl setup provides a robust foundation for the portfolio's multi-language support. By centralizing locale management in server actions and utilizing cookies, the application ensures that user preferences are preserved across reloads without cluttering the URL structure. This approach seamlessly handles the complexities of RTL/LTR layout transitions required for English and Persian support.