Etyma 1.0 is stable

Typed i18n. Real SSR. Clean Angular APIs.

Etyma gives Angular, AnalogJS and Astro teams typed JSON catalogs, MessageFormat 2 with typed params, localized URLs, translated SSR HTML and hydration-safe lazy locale loading.

pnpm add @etyma/core

Angular: 21 and 22
AnalogJS: 2.6 and 2.7
Astro: 6 and 7
Locales: EN / ES / UK

const i18n = defineRemoteI18n({
  locales: ['en', 'es', 'uk'],
  sourceLocale: 'en',
  contract,
  loaders: {
    en: createHttpMessageLoader(localeUrl),
    es: createHttpMessageLoader(localeUrl),
    uk: createHttpMessageLoader(localeUrl)
  }
});

SSRLocalized HTML ships from the server before hydration starts.

Why it exists

The i18n layer Angular apps should have by default.

Typed internationalization for Angular and AnalogJS

Typed keys and params

The source catalog defines the key contract, and each message’s MessageFormat 2 variables become required params: a :number variable takes a number, a :datetime one a date. Mistakes fail in TypeScript, not in the UI.

SSR first

A localized URL renders localized HTML on the server, transfers the catalog, and hydrates without loading that locale again.

Edge-ready

The Analog integration is tested through a Cloudflare Pages build so package output and runtime behavior stay honest.

Stable since 1.0

A promise you can build a product on.

Every documented export, generated format, diagnostic code and CLI exit code keeps its meaning for every 1.x release. New capabilities arrive as minors, never as surprises.

Stable API

Runtime exports and public types follow semver across all six packages.

Stable contract

One generated shape. New metadata is a new optional field, never a new format.

Stable diagnostics

Codes are namespaced and never renamed, removed or re-graded within a major.

Stable CLI

Exit 0 on success, 1 on a validation or stale-contract failure, 2 on usage or I/O errors.

Caught in the editor

Mistakes fail in TypeScript, not in production.

Keys, parameter names and parameter types come from your catalog. A typo, a missing variable or a string where a number belongs is a compile error — in code and in Angular templates.

const { t } = injectI18n(i18n);

t('home.title');                  // ok
t('home.titel');                  // unknown key
t('footer.rights');               // year required
t('footer.rights', { year: 'x' }); // not a number
t('footer.rights', { year: 2026 });

How it works

Define once. Route by URL. Hydrate without flicker.

Etyma keeps the source catalog typed, secondary catalogs lazy, and the visible page aligned with the address bar.

Author catalogs

JSON stays readable while TypeScript keeps the source locale as the contract.

Serve localized URLs

The source locale remains clean, while secondary locales live under stable prefixes.

Transfer the active locale

SSR sends the catalog the page used, so hydration does not refetch it or flash English.

Tooling

Catalogs and contracts checked in CI, not in production.

@etyma/cli validates every locale against the source and generates the typed contract for a JSON source. --check verifies the committed contract without writing anything, so a stale type never reaches main. etyma analyze finds unknown keys in JS/TS, Angular templates and Astro files.

# CI: validate Glossa, then build
etyma validate --remote "https://glossa.andersseen.dev/i18n/etyma-www/{locale}.json" \
  --locales en,es,uk --source en
pnpm typecheck && pnpm build

Validate catalogs

Missing and extra keys, invalid MessageFormat 2 and variable drift, for local files or public remote catalogs.

Generate the contract

Exact keys, variable names and MF2 functions — never message text. Deterministic, committed, readable in review.

Verify it in CI

Exit 1 when the committed contract is missing or out of date — even when a variable only changed from :number to :datetime.

Packages

One portable core, adapters for three frameworks, tooling for CI.

@etyma/core owns catalogs, MessageFormat 2 and types. @etyma/angular, @etyma/analog and @etyma/astro bring them to each framework. @etyma/tooling and @etyma/cli keep catalogs and contracts honest.

@etyma/core

@etyma/angular

@etyma/analog

@etyma/astro

@etyma/tooling

@etyma/cli

Ship typed, translated, server-rendered.

Start with the docs, or read the source. Etyma is MIT licensed and developed in the open.