Catch stale and unreviewed translations in CI, not in production.
Translation files in a repository hold only values. When the source text changes, nothing marks the translations out of date, so stale translations ship silently.
LingoTracker stores a status next to every translation in your Git repo. A changed source string marks its existing translations stale. Untranslated copies stay new. lingo-tracker validate fails CI while anything is missing, stale, unreviewed or invalid ICU for its locale. It is built for Angular apps using Transloco. One npm package gives you a CLI, a local web UI with a REST API, and an installable skill for AI coding assistants. There is no hosted service and no account.
Status: 1.0. The CLI and API are stable. Every pull request to develop runs unit tests and CLI end-to-end tests for the affected projects. The web UI has a Playwright end-to-end suite. See the roadmap and the changelog.
lingotracker-1.0-release-90s.mp4
A 90-second tour of LingoTracker 1.0. Want more detail? Watch the 2½-minute version or LingoTracker in 30 seconds.
Gate the release.
- Every translation is
new,translated,staleorverified. Checksums mark existing translationsstalewhen the source changes. Untranslated copies staynew. validatefails CI on missing, stale or unreviewed strings. Use--allow-translatedfor a staging gate.- Every value compiles as an ICU message under its own locale. A plural that is valid in English but invalid in Japanese is caught before it renders empty.
- Pull requests show exactly which strings and statuses changed, because values and metadata are plain JSON per folder.
Generate runtime bundles.
bundlewrites one JSON file per locale from any mix of collections, key patterns and tags.- It can emit a TypeScript constant tree, so a mistyped key fails to compile.
bundle --debug-keyswrites an extra bundle whose values are the keys themselves. Load it as its own locale to identify strings in the app.- Read-only collections let you bundle translations shipped by a component library without editing them.
add-collectiondefaults folders undernode_modulesto read-only.
Translate and review strings.
- Export
newandstalestrings as XLIFF 1.2 or JSON. Import withtranslation-servicefor vendor deliveries,verificationfor approvals,migrationfor existing files, orupdatefor bulk corrections that keep the current status. - Import repairs placeholder names that translators changed. It rejects translations that altered a protected term.
- Protected terms survive translation. Preferred terminology flags discouraged wording in source text.
- When enabled with a Google Cloud Translation v2 key, auto-translation fills target locales as you add strings. It skips complex ICU and any result with a lost or corrupted placeholder or a missing protected term. Results are marked
translated, neververified.
Work in the UI or from an assistant.
- A local web UI lets you browse, search and filter by status. You edit with similar-string suggestions and run exports, imports and bundles with a live preview.
install-skillwrites a skill tailored to your collections. Claude Code or a similar assistant can then find hardcoded strings, reuse keys, add resources and update components.
Adopting it. Existing Transloco or i18next JSON moves in through the migration import strategy. The guide lists what each format keeps and loses. Gettext and CSV need a short conversion step. See the migration guide. After you resolve a merge conflict in the JSON files, run normalize. It recomputes checksums and reapplies the status rules. See the normalize guide.
Requires Node.js 24.15 or later within the 24 line, or Node.js 26 or later.
pnpm add -D @simoncodes-ca/lingo-tracker # or npm install --save-dev / yarn add -D
# Create .lingo-tracker.json
npx lingo-tracker init \
--collection-name main --translations-folder src/i18n \
--base-locale en --locales en fr-ca es \
--setup-bundle true --bundle-dist ./src/assets/i18n \
--type-dist-file ./src/generated/translation-tokens.ts
# Add a string, translate it, and generate the runtime files
npx lingo-tracker add-resource --key common.buttons.save --value "Save" --comment "Button on edit forms"
npx lingo-tracker edit-resource --key common.buttons.save --locale fr-ca --locale-value "Enregistrer"
npx lingo-tracker bundle
# Open the web UI at http://localhost:3030
npx lingo-tracker-app
# Gate the release
npx lingo-tracker validate # exits 1: fr-ca not verified, es still EnglishThe Getting Started guide explains each step and what the files look like.
- It does not host translations or coordinate translators. Hand-off happens through exported files.
- It has no user accounts or history beyond what Git gives you.
- Machine translation supports Google Cloud Translation v2 only and skips plural, select and formatted ICU messages.
- The web UI runs locally without authentication. It is for one developer's machine, not a shared server.
- Bundles assume
@jsverse/transloco-messageformatunlessruntimeis"transloco"in.lingo-tracker.json, for apps on plain Transloco where{and'are literal text.initdetects it frompackage.json. - Other libraries can consume the nested JSON bundles when their placeholder syntax matches, with ICU-to-Transloco conversion turned off.
The full documentation is at simoncodes-ca.github.io/lingo-tracker.
| Page | Covers |
|---|---|
| Getting Started | Install, init, first resource, first bundle |
| Concepts | Keys, folders, the two files, statuses and checksums |
| Configuration | Every field of .lingo-tracker.json |
| CLI Reference | Every command, flag and exit code |
| API Reference | Every endpoint of lingo-tracker-app, with Swagger UI at /api |
| Tracker UI | The web application |
| Guides | Bundling, translation workflow, CI/CD, migration, normalize, AI assistant |
| Features | Validate, export, import, type generation, terminology, glossary |
| Changelog | Release history |
For contributors, architecture-docs describes the monorepo, data model and application layers.
See CONTRIBUTING.md for setup, tests and the commit convention. To report a vulnerability, see SECURITY.md.