Internationalization (i18n)
Relevant source files
The following files were used as context for generating this wiki page:
StatusBeam provides a framework-free internationalization system primarily housed within packages/core and utilized by the Astro-based web application. The system supports multiple locales including English (en), Simplified Chinese (zh), Japanese (ja), and Korean (ko). It is designed to ensure that every locale is a distinct URL to prevent edge cache fragmentation on the Accept-Language header.
The i18n implementation covers UI translations, date formatting, and automated locale negotiation based on user preferences (cookies), browser headers, and system configuration.
Sources: README.md:204-207, ARCHITECTURE.md:144-146, apps/web/astro.config.ts:25-33
Architecture and Routing
StatusBeam uses URL-prefixed routing for internationalization. Each supported language exists as a distinct path (e.g., /en/, /ja/). This architecture allows the Cloudflare edge cache to store localized versions of the status page independently. The bare root URL (/) is handled by middleware that performs locale negotiation and redirects the user to the appropriate prefixed path.
Supported Locales
| Locale Code | Language |
|---|---|
en | English (Default) |
zh | Simplified Chinese |
ja | Japanese |
ko | Korean |
Sources: README.md:204-207, apps/web/astro.config.ts:25-33, packages/core/src/i18n.test.ts:32-35
Locale Negotiation Flow
The system follows a specific priority order when determining the user's locale:
- Locale Cookie: A
localecookie set when a user manually selects a language. - Accept-Language Header: The preferred language communicated by the visitor's browser.
- Deployment Configuration: The
theme.localespecified instatus.config.yml. - Default: English (
en).
The negotiation logic is implemented in packages/core/src/i18n.ts via the negotiateLocale function. The middleware in apps/web/src/middleware.ts executes this logic during request handling.
Sources: README.md:209-215, packages/core/src/i18n.test.ts:121-131, apps/web/astro.config.ts:34-37
Core Implementation
The internationalization logic is framework-free and resides in packages/core/src/i18n.ts. It provides utilities for matching locales, resolving regional variants, and retrieving translation dictionaries.
Key Functions
| Function | Purpose |
|---|---|
resolveLocale(tag) | Collapses regional variants (e.g., en-US to en, zh-CN to zh). |
matchLocale(tag) | Returns a supported locale code if the input matches, otherwise null. |
getDict(locale) | Retrieves the full translation dictionary for a specific locale. |
formatDay(date, locale) | Formats a UTC ISO date string into a localized format (e.g., Jul 5, 2026). |
negotiateLocale(cookie, preferred) | Compares cookie and browser signals to select the best supported locale. |
Sources: packages/core/src/i18n.test.ts:22-131, ARCHITECTURE.md:144-146
Data Structure: Translation Dictionaries
Dictionaries are structured objects containing localized strings for various UI components, including the status banner, charts, and timelines.
Function-valued entries in the dictionary allow for dynamic string interpolation, such as timeline.windowStart(90) producing "90 days" in English or its equivalent in other languages.
Sources: packages/core/src/i18n.test.ts:1-20, packages/core/src/i18n.test.ts:68-80
Date and Time Formatting
StatusBeam ensures consistent date rendering across different host timezones by explicitly using UTC for localized date formatting. This prevents the "calendar day" from shifting based on the server's local time.
The formatDay function utilizes Intl.DateTimeFormat with a fixed timeZone: 'UTC' configuration. It is designed to be resilient, degrading to the raw input string if the provided date is malformed (e.g., 20xx-07-05) rather than throwing an error that would crash SSR.
Sources: packages/core/src/i18n.test.ts:88-119
Configuration
The default deployment locale is configured in the status.config.yml file under the theme block. This serves as the final fallback if no user preference or browser language matches the supported set.
theme:
# Fallback UI language (en | zh | ja | ko)
locale: en
Sources: status.config.example.yml:85-90, README.md:213-214
Conclusion
The internationalization system in StatusBeam is a core component that enables global service monitoring visibility. By combining shared logic in packages/core with Astro's URL-prefixed routing and Cloudflare's edge capabilities, the project achieves localized rendering without compromising cache performance or server stability. All components, from the incident timeline to uptime badges, utilize these i18n primitives to provide a consistent multi-language experience.