Internationalization (i18n)
Relevant source files
The following files were used as context for generating this wiki page:
The Internationalization (i18n) system in ATMOS is a centralized architecture designed to provide multi-language support across the monorepo's applications. It leverages the next-intl framework to manage localized routing, message loading, and type-safe navigation. By utilizing a dedicated package (@atmos/i18n), the project ensures consistent locale configuration and translation patterns between the web application and the landing page.
The system supports a locale-based routing strategy where the current language is typically reflected in the URL path. It provides utilities for both Server and Client components to access translations efficiently while maintaining strict TypeScript definitions for locale codes and names.
Sources: packages/i18n/README.md:1-15, apps/landing/README.md:10-15
Architecture Overview
The i18n system is structured as a shared package that defines core configurations and utilities, which are then consumed by individual applications. This ensures that language settings (like supported locales and default languages) are synchronized across the entire project.
Core Architecture Flow
The following diagram illustrates how the shared @atmos/i18n package provides the necessary routing and configuration logic to an application (e.g., the Landing Page), which then loads locale-specific messages.
The shared package manages the "how" (routing and logic), while the individual apps manage the "what" (actual translation strings).
Sources: packages/i18n/README.md:18-35, apps/landing/README.md:38-55
Core Configuration
The foundational settings for internationalization are defined in src/config.ts. This file acts as the single source of truth for supported languages within the ATMOS ecosystem.
Locale Settings
The system currently supports English and Chinese, with English set as the default locale.
| Property | Value | Description |
|---|---|---|
locales | ["en", "zh"] | The list of supported language codes. |
defaultLocale | "en" | The fallback language used when no locale is detected. |
localeNames | en: "English", zh: "中文" | Human-readable names for the supported locales. |
Sources: packages/i18n/README.md:41-55, packages/i18n/src/config.ts
Type Safety
The system uses TypeScript's as const assertions to derive types from the configuration, ensuring that locale-related variables are restricted to the supported values.
export const locales = ["en", "zh"] as const;
export type Locale = (typeof locales)[number];
Sources: packages/i18n/README.md:43-44, packages/i18n/src/types.ts
Routing and Navigation
Routing is handled via next-intl/routing, which manages the prefixing of URLs with locale codes.
Routing Logic
The routing configuration determines how locales are represented in the URL. By default, the localePrefix is set to "as-needed", meaning the default locale might not require a prefix, while others do.
Navigation Utilities
To maintain the locale context during user navigation, the system provides specialized components and hooks. These are exported from src/navigation.ts and wrapped with the project's routing rules.
- Link: A localized replacement for the standard Next.js
Link. - useRouter: A hook to perform programmatic navigation while preserving the current locale.
- usePathname: Returns the current pathname without the locale prefix.
Sources: packages/i18n/README.md:87-95, packages/i18n/src/navigation.ts
Translation Loading
Translation strings are stored in JSON files within the messages/ directory of each specific application. This allows different apps (like the dashboard vs. the landing page) to have distinct translation keys.
Request Configuration
The getRequestConfig function in src/request.ts handles the dynamic import of these JSON files based on the detected locale during a server-side request.
Translation File Structure
Messages are organized by namespaces (e.g., HomePage, Navigation) to prevent key collisions and improve maintainability.
{
"HomePage": {
"title": "Welcome to ATMOS",
"description": "AI-first workspace"
}
}
Sources: packages/i18n/README.md:155-170, apps/landing/README.md:105-115
Usage Patterns
The i18n system distinguishes between Server and Client components for optimal performance and SEO.
Implementation Methods
| Context | Function/Hook | Source |
|---|---|---|
| Server Components | getTranslations(namespace) | next-intl/server |
| Client Components | useTranslations(namespace) | next-intl |
| Static Params | generateStaticParams() | Used in layout.tsx for SSG |
Examples
Server Component Usage:
import { getTranslations } from "next-intl/server";
export default async function Page() {
const t = await getTranslations("HomePage");
return <h1>{t("title")}</h1>;
}
Sources: packages/i18n/README.md:195-215
Conclusion
The Internationalization system in ATMOS provides a robust, type-safe framework for multi-language support. By centralizing the configuration in the @atmos/i18n package and utilizing next-intl for routing and message loading, the project achieves a seamless localized experience across different applications. This architecture simplifies the addition of new languages and ensures that navigation and translation logic remain consistent throughout the monorepo.
Sources: packages/i18n/README.md:280-300