i18n
Wavemap i18n is owned by @wavemap/i18n and consumed by the front end, backend error rendering, and automated email
copy adapters.
The package is more than a translation-file folder. It owns locale and namespace contracts, runtime resource loading, grammar helpers, generated static assets, and source-level verification for the string identities that cross package, database, API, and UI boundaries.
This section promotes the stable parts of packages/i18n/i18n-documentation.md into the docs site. The package-local
Markdown can remain useful as deep implementation notes while this section becomes the curated developer reference.
Package Layers
Section titled “Package Layers”| Layer | Location | Responsibility |
|---|---|---|
common | packages/i18n/src/common | Shared constants and types that could later become reusable outside Wavemap. |
wavemap | packages/i18n/src/wavemap | Wavemap-specific namespace taxonomy and domain-facing i18n constants. |
merge | packages/i18n/src/merge | Runtime-facing locale, namespace, and initial-load composition. |
core | packages/i18n/src/core | Client/server i18n runtime helpers, resource loading, grammar, and strict mode behavior. |
env | packages/i18n/src/env | Typed client and server i18n environment readers. |
locales | packages/i18n/locales | Source translation sheets grouped by locale and namespace. |
The main runtime contract is intentionally composed in merge. Application code should not rediscover locale and
namespace sets by walking the filesystem.
Reading Path
Section titled “Reading Path”- Translation Resources explains sheet filenames, key conventions, server error resources,
email resources, ICU usage,
_meta, and canonical ordering. - Runtime And Frontend explains client/server runtime boundaries, loading, backend error
rendering, email copy adapters, route locale normalization, providers, and
t()usage. - Assets And Delivery explains development rewrites, generated frontend assets, same-origin fallback, and CDN posture.
- Guardrails explains
pnpm verify:i18n, CI coverage, domain-code translation contracts, seed-source checks, and generated asset validation. - Contributor Workflows gives checklists for adding locales, namespaces, translated domain-code values, server errors, email copy, and reusable component label maps.
Page Guide
Section titled “Page Guide”| If You Are... | Start With |
|---|---|
| Adding or reviewing translation keys | Translation Resources |
| Wiring localized copy into React or server code | Runtime And Frontend |
| Changing generated assets, CDN behavior, or deploy-time i18n values | Assets And Delivery |
| Investigating CI failures or brittle domain-code seams | Guardrails |
| Adding a locale, namespace, translated code value, backend error, email, or component label map | Contributor Workflows |
Current Posture
Section titled “Current Posture”Frontend route localization, backend error localization, and automated email copy localization are active for the currently supported surfaces.
New i18n work should keep the current contracts intact:
packages/i18n/locales/**remains the source translation surface.pnpm verify:i18nis the source-level correctness gate.pnpm format:i18nis the local fixer for translation sheet ordering.- Generated frontend assets must match the package
I18N_VERSION. server--errorsowns backend-rendered user-facing error copy.email--*namespaces own automated email copy.- Large, reusable components should receive resolved grouped label maps rather than Wavemap translation keys.
- New server-side localization should use server-only helpers and isolated resources instead of reusing the client singleton.