Raypx

@raypx/i18n provides internationalization support using use-intl with URL-based locale routing. It handles locale detection, URL rewriting, message loading, and server-side request configuration.

Supported Locales

Locale	Label	Native Label
`en-US`	English	English
`zh-CN`	Chinese (Simplified)	Simplified Chinese

The default locale is en-US.

Core Exports

Routing

Export	Description
`routing`	Routing configuration object (locales, prefix, cookie, ignored paths)
`SUPPORTED_LOCALES`	Readonly array of supported locale codes
`DEFAULT_LOCALE`	The default locale (`"en-US"`)
`LOCALE_COOKIE_NAME`	Cookie name (`"raypx-locale"`)
`LOCALE_META`	Metadata map with labels and native labels for each locale
`isValidLocale(locale)`	Type guard to check if a string is a valid locale
`shouldIgnorePath(pathname)`	Check if a path should skip locale processing
`extractLocaleFromPath(pathname)`	Extract locale and stripped path from a URL path
`stripLocalePrefix(pathname)`	Remove locale prefix from a path
`localizePath(pathname, locale)`	Add locale prefix to a path
`createCookieHeader(locale)`	Create a `Set-Cookie` header string

Server

Export	Description
`getRequestConfig(input)`	Create the full i18n request config (locale, messages, timeZone)
`resolveRequestLocale(request)`	Detect locale from a Request object
`I18nRequestConfig`	Type for the request config object

Export	Description
`getCurrentLocale()`	Get the current locale from the URL or cookie
`deLocalizeUrl(url)`	Strip the locale prefix from a URL
`localizeUrl(url, locale?)`	Ensure a URL has a locale prefix
`switchLocalePath(pathname, locale)`	Get the path for switching to another locale

Messages

Export	Description
`getMessages(locale)`	Load translation messages for a locale
`AppMessages`	Type representing the full message structure

Routing Configuration

The routing object defines the core behavior:

export const routing = {
  locales: ["en-US", "zh-CN"] as const,
  defaultLocale: "en-US" as SupportedLocale,
  localeCookie: "raypx-locale",
  localePrefix: "always" as const,
  ignoredPathPrefixes: ["/api", "/__", "/llms"],
}

localePrefix: "always" -- every page URL includes the locale (e.g., /en-US/dashboard, /zh-CN/dashboard).
Ignored paths -- /api, /__ (internal), and /llms (LLM middleware) paths skip locale processing entirely.

Message Files

Translation messages are stored as TypeScript objects in packages/i18n/src/messages/:

The AppMessages type is inferred from the en-US messages file, ensuring all locales have the same shape.

Usage in Components

import { useTranslations } from "use-intl"

function WelcomePage() {
  const t = useTranslations("WelcomePage")
  return <h1>{t("title")}</h1>
}

Server-Side Request Config

For server components and server functions, use getRequestConfig:

import { getRequestConfig } from "@raypx/i18n"

export async function loader({ request }: { request: Request }) {
  const config = getRequestConfig(request)
  // { locale: "en-US", messages: {...}, timeZone: "America/New_York" }
}

Each locale maps to a default time zone:

Locale	Time Zone
`en-US`	`America/New_York`
`zh-CN`	`Asia/Shanghai`

@raypx/i18n