Overview
Etyma is a small toolkit for translating Angular, AnalogJS and Astro applications: JSON
catalogs, typed message keys, MessageFormat 2 formatting, locale-aware routing, server- and
build-time translations, and the localized <head> that makes a translated page findable.
Status: published, with a semver-stable public API. Every package is on npm. The runtime
trio (core, angular, analog) versions together and is used by Volt UI; @etyma/astro,
@etyma/tooling and @etyma/cli version independently, with @etyma/astro running a
production Astro 6 site. The API is small on purpose and the release gates exercise packed
packages. What the stability promise covers is in V1.md; read
Non-goals before adopting it.
Why Etyma exists
Most Angular i18n stacks make one of three trade-offs: translation keys are untyped,
localized routes are bolted on after routing, or SSR ships source-language HTML and lets
hydration fix it later. Etyma keeps those pieces in one contract:
- the source catalog is the type source;
- the URL is the locale source of truth;
- the server renders the requested language first;
- the browser hydrates with the catalog the server already used.
What it does today
- JSON catalogs first.
i18n/en.json, i18n/es.json, i18n/uk.json. Nested keys,
addressed as nav.docs; arrays of strings, addressed by index as steps.0.
- Typed keys.
t('footer.foo') does not compile when the source catalog has no
footer.foo. Inferred from the source catalog's type — no code generator, no build step.
- Typed params, when you want them.
t('welcome') does not compile when the message is
'Hello, {$name}!': inferred for defineMessages() catalogs, and available for JSON
catalogs through an optional generated contract — see Typed params.
- MessageFormat 2, through the
messageformat
reference implementation. Plurals, selects, numbers and dates come from CLDR and Intl,
not from anything Etyma invented.
- Signals.
i18n.locale() is a signal, t() reads it, and a template that calls t()
re-renders when the language changes. No RxJS in the public API. No Zone.js anywhere.
- Lazy catalogs. Only the source language is in the initial bundle. Every other locale
is a dynamic import that loads when a visitor asks for it.
- URL-driven locale.
/docs is English, /es/docs is Spanish, /uk/docs is Ukrainian.
The URL is the only source of truth — nothing is read from or written to localStorage.
The source locale is canonical only without a prefix; /en/docs is not a duplicate route.
- Server-rendered translations.
GET /es/docs returns Spanish HTML. Not English HTML
that becomes Spanish after hydration.
- Hydration without a second fetch. The catalog the server rendered with is transferred
to the browser, so there is no locale round trip and no flash of the source language.
- Localized SEO.
<html lang>, dir, a canonical URL, an absolute hreflang set and
x-default — kept correct after client-side navigation, not only on a direct visit.
- Safe by default. A translation is text. Nothing in the normal rendering path goes near
innerHTML. Messages that need structure come back as MessageFormat 2 parts.
Packages
| Package | What it is | Depends on |
|---|
@etyma/core | The portable engine: catalogs, MessageFormat 2, locale routing, lazy loading. No framework, no DOM, no Node built-ins. | messageformat |
@etyma/angular | Signal-native Angular bindings: provideEtyma, injectI18n, injectT, SSR transfer state. | @etyma/core, Angular 21 or 22 |
@etyma/analog | The AnalogJS integration: locale-prefixed routes, request-scoped SSR, localized <head>. | @etyma/angular, Analog 2.x |
@etyma/astro | The Astro integration: request/render-scoped translation on top of Astro's own i18n routing. No Angular, no Analog. Versions independently. | @etyma/core, Astro 6.x or 7.x |
@etyma/tooling | Development-time catalog validation: key parity, MessageFormat 2 syntax, external variable contracts, as diagnostics. Static JS/TS message-usage analysis under /source. Vite plugins under /vite. Not a runtime dependency. | @etyma/core |
@etyma/cli | The etyma binary. validate checks catalogs, contract generates typed contracts, and analyze reports static JS/TS message usage. Not a runtime dependency. | @etyma/tooling |
여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗
