Project
FAQ
Questions that come up before the first build.
Does switching language need a reload?
Section titled “Does switching language need a reload?”No. The locale is read at call time; setLocale updates one store and notifies subscribers. Key a
root on useLocale() to remount it, or pass { locale } per call to keep state
(Language switching).
What can vary at run time?
Section titled “What can vary at run time?”| What | How |
|---|---|
| Values | Arguments: m.cart_items({ count }) picks the plural branch at call time; count is type-checked. |
| The message, from a set the build knows | groups: { errors: 'errors' } generates a typed record and key union; an unknown code in errors[code]({ seconds }) is a type error. A dynamic call passes every member’s arguments, and the build warns when they disagree (Dynamic keys). |
| CMS content or user-typed text | Not a message: it cannot be checked, typed or recorded, and formatting it would need a browser ICU parser, which generated code never ships. Runtime format() is deferred. |
Do I have to rewrite my i18next JSON?
Section titled “Do I have to rewrite my i18next JSON?”No. Point catalogs at your files; each is classified on its own, so ICU and i18next files mix.
{{name}} and plural suffixes are converted in memory, never written. $t( nesting and inline
formatters are reported, not converted (Importing i18next catalogs).
Is there a bundler plugin?
Section titled “Is there a bundler plugin?”No, and no AST pass over your code: loclizr build writes plain ESM into src/loclizr. The
example app’s Vite config only reruns build on catalog changes.
Next.js, React Server Components, React Native?
Section titled “Next.js, React Server Components, React Native?”Generated code imports no framework and runs in all three; only React on Vite is tested. Server rendering covers Web Fetch handlers, plus a headers primitive for Express and Fastify.
| Target | Status |
|---|---|
| Next.js App Router | Not first-class in v0.1, no example |
| React Server Components | loclizr/react emits no 'use client'; add your own where a boundary is needed |
| React Native | Works without document. Hermes on Android needs the intl build for Intl.PluralRules, NumberFormat and DateTimeFormat. |
Cannot find module ‘./loclizr/messages’ (TS2307)
Section titled “Cannot find module ‘./loclizr/messages’ (TS2307)”src/App.tsx(4,20): error TS2307: Cannot find module './loclizr/messages' or its corresponding type declarations.The tree is not built yet: a fresh clone, or an editor or CI run before the first build. Run
npx loclizr build; the predev, prebuild and pretypecheck scripts from init rebuild it first.
Will one missing translation fail my build?
Section titled “Will one missing translation fail my build?”Yes: by default it fails prebuild.
| Command | Result |
|---|---|
loclizr build (prebuild) |
Exits 1, but still writes the tree, filled from the fallback chain, so typecheck works. |
loclizr build --no-fail (predev, prepare) |
Same diagnostics; exits 0 once output is written, so a dev server starts. |
loclizr check (CI) |
The gate; no --no-fail. |
Translators work after the merge? severity: { 'missing-translation': 'warn' } trades the gate for
a reminder; Translation workflow has the cost.
Can I turn a check off?
Section titled “Can I turn a check off?”Any rule except three: severity: { 'unused-message': 'off' } in loclizr.config.ts sets a rule,
by the name printed beside its code, to off, warn or error. A code such as LZ5004 is
rejected as LZ1001.
config-invalid, outdir-unsafe and output-unwritable cannot be re-levelled; lowering one would
let the tool quietly do what it must never do. Warnings fail a run only with --max-warnings.
What is the context record for?
Section titled “What is the context record for?”Whoever translates next. Per message:
- canonical source text and its hash
- argument names and types
- plural or select shape
- your description and placeholder notes
- file and enclosing function of each use
- per-locale status
build writes it at the record path for you to commit. check compares the committed copy with what the
tree now produces, so a string edit without its context fails the pull request.
How is that different from a TMS agent that writes context?
Section titled “How is that different from a TMS agent that writes context?”| Property | TMS agent | Context record |
|---|---|---|
| Output | Different text each run | Same bytes for same inputs |
| Cost | Billed per run | Nothing per run |
| Lives in | A vendor database | git |
| Arrives | After code review | With the diff, reviewed |
It stays yours across vendors.
Should the generated files be in git?
Section titled “Should the generated files be in git?”No by default: build writes a self-ignoring .gitignore in src/loclizr, and the prepare,
predev, prebuild and pretypecheck scripts from init regenerate the tree on a fresh clone.
Commit locales/loclizr.context.json instead. To commit the tree, delete that .gitignore;
check then compares it too.
Does the compiler ever write my catalogs?
Section titled “Does the compiler ever write my catalogs?”Never. It writes the tree and the record, and build deletes only outDir files carrying
its header; others are reported and left alone.