Guides

Troubleshooting, migration from ngx-translate, and package version compatibility.

Troubleshooting

Common issues when wiring the library into an Angular app.

Empty text or layout jump (FOUC / CLS)

Symptom Labels render blank, then pop in; or the whole block appears late

Likely cause Namespace still loading, wrong loader for SSG, or JSON not served at the expected URL

FixUse optional chaining with select() (not @if around the whole UI). Prefer importLoader for prerender/SSG. For httpLoader('/i18n'), put files in public/i18n/{lang}/{ns}.json. Use ready() only for a branded shell if needed.

Raw key shown (e.g. common:nav.home)

Symptom UI shows the key string instead of the translation

Likely cause Key missing from JSON, wrong namespace, or typo in path

FixConfirm the key exists under the active language. Run ats check --i18n src/i18n --src src. Customize with missingKeyHandler if you want a different fallback.

Language does not switch

Symptom Calling a switch method does nothing or throws

Likely causeUsing a non-existent API, or language not in supportedLangs

FixUse await i18n.setLang('pt-BR') (not use()). Ensure the code is listed in supportedLangs. Configure storageKey to persist the choice.

Pipe shows nothing or wrong key

Symptom Translate pipe empty or prints an unexpected string

Likely causeMissing namespace: separator, or pipe not imported

FixKeys must be namespace:path (e.g. 'common:nav.home'). Import TranslatePipe in the component imports array.

Hydration mismatch (NG0501) or double fetch

Symptom Console hydration errors, or client refetches core namespaces

Likely cause Server and client language differ, or TransferState not applied

FixKeep provideTranslation() on both sides (it owns TransferState). For request-based language, add provideTranslationSSR({ langFromRequest }) on the server. Prefer importLoader for pure SSG.

CLI cannot find i18n files

Symptom Commands exit with directory not found

Likely causeDefaults assume src/i18n; only editor/mcp auto-discover

FixPass -i src/i18n or --i18n. For HTTP runtime files under public/i18n, either mirror them under src/i18n for tooling or point flags at public/i18n.

Validate/clean use the wrong reference language

SymptomReference is de (or another locale) instead of en

Likely causeWithout --default-lang, the first alphabetically sorted folder wins

FixAlways pass --default-lang en (or your source locale) in scripts and CI.

instant() returns empty string

Symptom Imperative read is blank even though JSON exists

Likely causeLazy namespace never requested yet; first sync call still returns ''

FixAwait ensureNamespaces(['settings']) first, or use reactive translate() / select() for UI.

ats check reports false positives

SymptomKeys like og:title or sample snippets fail CI

Likely causeAny quoted ns:key string is treated as a reference

FixPoint --src at application code (not docs samples), or keep sample keys present in JSON packs.

ats translate / editor LLM fails

Symptom Connection errors or empty model responses

Likely cause Ollama not running, wrong host/model, or model not pulled

FixInstall Ollama, run ollama pull gemma3:12b (or your model), confirm ollama list, and pass --host/--model if not using defaults.

Migration from ngx-translate

Map common @ngx-translate/core patterns to this library. Concepts are similar (namespaces ≈ JSON files, keys ≈ dotted paths) but the reactive model is signal-based.

ngx-translate	This library
`TranslateModule.forRoot({ loader: ... })`	`provideTranslation({ defaultLang, supportedLangs, coreNamespaces, loader })` in app config
`inject(TranslateService)`	`inject(TranslationService)`
`translate.get('KEY')` / `stream('KEY')`	`i18n.translate('ns:key')` returns a `Signal<string>` — read with `()`
`translate.instant('KEY')`	`i18n.instant('ns:key')` — non-reactive; preload with `ensureNamespaces` if needed
`{{ 'KEY' \| translate }}` or `{{ 'KEY' \| translate:{x:1} }}`	`{{ 'ns:key' \| translate }}` — import `TranslatePipe`; keys need a namespace prefix
`translate.use('fr')`	`await i18n.setLang('fr')`
`translate.currentLang` / `onLangChange`	`i18n.lang()` signal; UI updates when signals are used
Custom `TranslateLoader` / `TranslateHttpLoader`	`httpLoader('/i18n')` or `importLoader((lang, ns) => import(...))`
Often one file per language (`en.json`)	One folder per language, one file per namespace: `en/common.json`, `en/home.json`

Suggested steps

Install @angular-translation-service/core and add provideTranslation next to (or replacing) ngx-translate providers.
Split monolingual JSON into {lang}/{namespace}.json. Keep nested objects; use ns:path in code.
Replace TranslateService.use with setLang, and get/stream with translate() signals or select().
Update templates to namespace:key pipe form and import TranslatePipe per standalone component.
Remove @ngx-translate/* once screens are migrated. Add ats check / ats validate --default-lang en to CI.

Notes

Interpolation uses {name} in JSON (double braces still accepted).
No built-in ICU plurals — use separate keys and conditions, or keep a small helper.
There is no onLangChange stream; depend on signals inside computed() / templates.

Version compatibility

Core and CLI are published independently. Pair recent releases unless a changelog entry requires a specific combo.

Package	Current	Notes
`@angular-translation-service/core`	`0.3.4`	Angular peer range ^19 – ^22. Signal API: select / translate / instant / setLang.
`@angular-translation-service/cli`	`0.4.7`	Binary `ats`. Type generation augments core; keep CLI ≥ the version that introduced your workflow (scan, mcp, editor).

Angular support

Peer dependencies accept Angular 19, 20, 21, and 22. The docs app tracks the latest major used in the monorepo toolchain.

Recommended pairing

Install the latest core and latest CLI together:

npm install @angular-translation-service/core
npm install -D @angular-translation-service/cli

Notable pairings

core 0.3.4 + cli 0.4.6 — dotted-key longest-match resolution aligned across runtime and check/validate
core 0.3.2 + cli 0.4.4 — Angular 22 peer range
core 0.2.1+ — package renamed to @angular-translation-service/core (update imports)
See CHANGELOG.md in the repository for full release notes and required upgrades.