Skip to main content

Getting Started

This guide installs LingoTracker, creates a project, adds a first string, generates a bundle and opens the web UI. It takes about ten minutes.

Requirements​

  • Node.js 24.15 or later in the 24 line, or Node.js 26 or later
  • A package manager: pnpm, npm or yarn

Install​

Install the package as a development dependency of the project that owns the translations.

pnpm add -D @simoncodes-ca/lingo-tracker
# or
npm install --save-dev @simoncodes-ca/lingo-tracker
# or
yarn add -D @simoncodes-ca/lingo-tracker

The package installs two commands:

CommandPurpose
lingo-trackerThe CLI
lingo-tracker-appThe web UI and its REST API

Run them with npx, or add scripts to package.json. The examples below use npx.

1. Initialize the project​

Run init in the folder that will hold .lingo-tracker.json. The CLI reads the config file from the directory you run it in (or from INIT_CWD under a package-manager script), never from a parent folder.

Interactive:

npx lingo-tracker init

Non-interactive, which is the form to copy into scripts:

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 \
--bundle-name "{locale}" \
--type-dist-file ./src/generated/translation-tokens.ts
FlagMeaning
--collection-nameName of the first collection. A collection is one translations folder.
--translations-folderWhere LingoTracker stores its own files. Keep this separate from the bundle output folder.
--base-localeThe locale you author in.
--localesEvery locale the project supports, including the base locale. Bundles are produced for this list.
--setup-bundle trueCustomize the default bundle instead of accepting the defaults.
--bundle-distFolder the runtime JSON files go to, the one your app loads from.
--bundle-nameFile name pattern. {locale} becomes en, fr-ca, and so on.
--type-dist-fileEnables TypeScript key generation and names the output file.

The result is a .lingo-tracker.json like this:

{
"exportFolder": "dist/lingo-export",
"importFolder": "dist/lingo-import",
"baseLocale": "en",
"locales": ["en", "fr-ca", "es"],
"collections": {
"main": {
"translationsFolder": "src/i18n"
}
},
"bundles": {
"main": {
"bundleName": "{locale}",
"dist": "./src/assets/i18n",
"collections": "All",
"typeDistFile": "./src/generated/translation-tokens.ts"
}
}
}

Commit this file. init writes nothing else. The translations folder is created when you add the first resource.

Two things to know:

  • Without --locales, the global locales list is empty. Add locales before you bundle.
  • If a config file already exists, init prints a note and exits without changing it.

The full field reference is in Configuration.

2. Add a resource​

A resource is one source string with a dot-delimited key. The key decides where the files go: common.buttons.save is stored in src/i18n/common/buttons/.

npx lingo-tracker add-resource \
--key common.buttons.save \
--value "Save" \
--comment "Button label on every edit form"

With one collection configured there is no need to pass --collection. The command creates two files:

src/i18n/common/buttons/resource_entries.json

{
"save": {
"source": "Save",
"comment": "Button label on every edit form",
"fr-ca": "Save",
"es": "Save"
}
}

src/i18n/common/buttons/tracker_meta.json

{
"save": {
"en": { "checksum": "c9cc8cce247e49bae79f15173ce97354" },
"fr-ca": { "checksum": "c9cc8cce247e49bae79f15173ce97354", "baseChecksum": "c9cc8cce247e49bae79f15173ce97354", "status": "new" },
"es": { "checksum": "c9cc8cce247e49bae79f15173ce97354", "baseChecksum": "c9cc8cce247e49bae79f15173ce97354", "status": "new" }
}
}

Each target locale starts as a copy of the source with status new. When a translation arrives, the status becomes translated. When the source changes later, it becomes stale. Concepts explains the lifecycle.

Add a translation now:

npx lingo-tracker edit-resource \
--key common.buttons.save \
--locale fr-ca \
--locale-value "Enregistrer"

3. Generate the bundle​

npx lingo-tracker bundle

This writes src/assets/i18n/en.json, fr-ca.json and es.json, plus src/generated/translation-tokens.ts:

export const MAIN_TOKENS = {
COMMON: {
BUTTONS: {
SAVE: 'common.buttons.save',
},
},
} as const;

export type MainTokens = typeof MAIN_TOKENS;

Configure your Transloco loader to load the generated files from src/assets/i18n, and use the constants in components. Add lingo-tracker bundle to a prebuild script so bundles are regenerated on every build. The Bundling guide covers multiple bundles, filtering and framework setup.

4. Gate releases with validate​

npx lingo-tracker validate

The command exits with code 1 while any translation is new, stale or translated but not verified, or when a value does not compile as an ICU message for its locale. Use --allow-translated for a staging gate. See Validate and the CI/CD guide.

5. Open the web UI​

npx lingo-tracker-app

Open http://localhost:3030. The app reads .lingo-tracker.json from the directory you started it in. From the UI you can browse and edit resources, manage collections and bundles, and run exports and imports with a preview. See Tracker UI.

Options:

SettingFlagEnvironment variableDefault
Port--port 4000LINGO_TRACKER_PORT3030
Bind address--host 0.0.0.0LINGO_TRACKER_HOST127.0.0.1
Extra allowed host namesLINGO_TRACKER_ALLOWED_HOSTSnone

The server binds to loopback by default, so only your machine can reach it. It has no authentication. If you bind to another address, every machine that can reach the port can read and write your translation files and list folders on the server. Keep it local unless you understand that trade-off. The API reference describes the Host and Origin checks that apply in every mode.

Next steps​