# loclizr

> A compiler for the contract between code and translations. `loclizr build` reads JSON catalogs, writes typed ESM message functions, runs catalog checks inside the build, and writes a context record per message that is committed with the string change. `loclizr check` is the CI gate.

Every link below is a Markdown rendering of the page at the same path without `.md`.

## Landing

- [Typed message functions and catalog checks from JSON](https://yasinmiran.github.io/loclizr/index.md): A compiler for the contract between code and translations.

## Start here

- [Introduction](https://yasinmiran.github.io/loclizr/start/introduction.md): What loclizr is, what it refuses to do, and who it is for.
- [Quickstart](https://yasinmiran.github.io/loclizr/start/quickstart.md): A fresh Vite app to typed messages, catalog checks, a language switch and a committed record.
- [Playground](https://yasinmiran.github.io/loclizr/start/playground.md): Five messages in 13 languages, compiled by loclizr for this site and running in your browser.
- [How it works](https://yasinmiran.github.io/loclizr/start/how-it-works.md): One pass over the catalogs, one lowered tree, three consumers.
- [Using loclizr with agents](https://yasinmiran.github.io/loclizr/start/agents.md): llms.txt, Markdown per page, Copy page, and a paste-ready AGENTS.md block.

## Guides

- [Catalogs and ICU messages](https://yasinmiran.github.io/loclizr/guides/catalogs.md): One JSON file per locale, ICU MessageFormat inside it.
- [Importing i18next catalogs](https://yasinmiran.github.io/loclizr/guides/i18next-import.md): Build an existing i18next JSON catalog in place, then move call sites over one at a time.
- [Migrating from FormatJS](https://yasinmiran.github.io/loclizr/guides/formatjs-migration.md): Compile react-intl messages to plain ICU catalogs, carry each description into the meta sidecar, then move call sites one at a time.
- [Language switching](https://yasinmiran.github.io/loclizr/guides/language-switching.md): The locale is read at call time, so a switch needs no reload.
- [Server rendering](https://yasinmiran.github.io/loclizr/guides/server-rendering.md): Request scoping with AsyncLocalStorage, and the hydration agreement.
- [Dynamic keys](https://yasinmiran.github.io/loclizr/guides/dynamic-keys.md): A typed lookup for a key chosen at run time from a known set.
- [Continuous integration](https://yasinmiran.github.io/loclizr/guides/continuous-integration.md): Put loclizr check in the pipeline; build stays in the scripts.
- [Testing](https://yasinmiran.github.io/loclizr/guides/testing.md): Set the locale per test, assert through the message functions, build the tree before Vitest or Jest runs.
- [Translation workflow](https://yasinmiran.github.io/loclizr/guides/translation-workflow.md): Who owns which file, what each pull request shape raises, and how a lagging locale is handled.
- [Monorepo](https://yasinmiran.github.io/loclizr/guides/monorepo.md): Two workspace layouts, what the usage scan binds across packages, and two trees in one program.
- [Publishing a library](https://yasinmiran.github.io/loclizr/guides/publishing-a-library.md): Ship the generated declarations with the package, keep loclizr a peer, and leave the locale to the app.

## Frameworks

- [React](https://yasinmiran.github.io/loclizr/guides/react.md): Key the root on useLocale, pass the locale per call where state must survive, render markup with Parts.
- [Svelte](https://yasinmiran.github.io/loclizr/guides/svelte.md): Svelte 5 runes over subscribe and getLocale, and the two ways to make markup follow a switch.
- [Vue](https://yasinmiran.github.io/loclizr/guides/vue.md): A Vue 3 composable over subscribe and getLocale, and the two ways to make templates follow a switch.
- [Solid](https://yasinmiran.github.io/loclizr/guides/solid.md): A Solid signal over the locale store, so messages update on a switch.
- [Astro](https://yasinmiran.github.io/loclizr/guides/astro.md): Prerendered pages per locale, or on-demand pages that follow Accept-Language, through one middleware.
- [Vanilla TypeScript](https://yasinmiran.github.io/loclizr/guides/vanilla.md): Messages in the DOM, a select that switches language, and subscribe re-rendering, with no framework.

## Reference

- [CLI](https://yasinmiran.github.io/loclizr/reference/cli.md): Three commands, eight options, two reporters, three exit codes.
- [Configuration](https://yasinmiran.github.io/loclizr/reference/configuration.md): Every field of loclizr.config.ts, its type, default and the rules on it.
- [Generated code](https://yasinmiran.github.io/loclizr/reference/generated-code.md): The generated tree, one message of each kind, and what tree-shakes.
- [Runtime API](https://yasinmiran.github.io/loclizr/reference/runtime-api.md): Every export of the four entry points, with its signature and one call.
- [Catalog checks](https://yasinmiran.github.io/loclizr/reference/checks.md): Fifty-nine rules by code, with default severity, fatal scope, trigger and fix.
- [Context record](https://yasinmiran.github.io/loclizr/reference/context-record.md): The schema of locales/loclizr.context.json, and what the gate compares.

## Project

- [Why loclizr](https://yasinmiran.github.io/loclizr/project/why.md): The argument this project is built on, and where the claim stops.
- [Comparison](https://yasinmiran.github.io/loclizr/project/comparison.md): Six libraries beside loclizr, and when to choose them instead.
- [Honest limits](https://yasinmiran.github.io/loclizr/project/limits.md): What v0.1 does not do, with the reason and the measured cost for each.
- [Security](https://yasinmiran.github.io/loclizr/project/security.md): What a build reads, writes and never does, with the source file that decides each.
- [Continuity](https://yasinmiran.github.io/loclizr/project/continuity.md): Maintainer count, release cadence, versioning, and what happens if this stalls.
- [Roadmap](https://yasinmiran.github.io/loclizr/project/roadmap.md): What is deferred past v0.1, and why each item was deferred.
- [FAQ](https://yasinmiran.github.io/loclizr/project/faq.md): Questions that come up before the first build.

## Documentation Sets

- [Abridged documentation](https://yasinmiran.github.io/loclizr/llms-small.txt): a compact version of the documentation for loclizr, with non-essential content removed
- [Complete documentation](https://yasinmiran.github.io/loclizr/llms-full.txt): the full documentation for loclizr

## Notes

- The complete documentation includes all content from the official documentation
- The content is automatically generated from the same source as the official documentation