Skip to main content

Configuration

All settings live in .lingo-tracker.json in the project root. init creates it. The CLI reads it from INIT_CWD when a package manager sets that variable, otherwise from the current directory. lingo-tracker-app reads it from the directory it was started in. Neither searches parent folders.

The file is plain JSON. Reading requires only a JSON object. Writes additionally require a baseLocale, an array for locales and an object for collections. When present, runtime is also checked on read and write; no other field is checked, so a misspelled field is ignored silently. Compare against this page when a setting has no effect.

Writes by the CLI, API or UI are guarded: if the file changed on disk between read and write, the write is refused with a conflict error instead of overwriting someone else's edit.

Complete example​

{
"baseLocale": "en",
"locales": ["en", "fr-ca", "es", "ja"],
"exportFolder": "dist/lingo-export",
"importFolder": "dist/lingo-import",
"tokenCasing": "upperCase",
"runtime": "transloco-messageformat",
"transformICUToTransloco": true,
"protectedTermsFile": ".lingo-tracker-protected-terms.json",
"preferredTerminologyFile": ".lingo-tracker-preferred-terminology.json",
"translation": {
"enabled": true,
"provider": "google-translate",
"apiKeyEnv": "GOOGLE_TRANSLATE_API_KEY",
"batchSize": 5,
"delayMs": 1000
},
"collections": {
"main": {
"translationsFolder": "apps/web/src/i18n",
"tags": ["web"]
},
"design": {
"translationsFolder": "node_modules/@acme/design-system/i18n",
"readOnly": true,
"protectedTermsFile": "node_modules/@acme/design-system/protected-terms.json"
}
},
"bundles": {
"web": {
"bundleName": "{locale}",
"dist": "./apps/web/src/assets/i18n",
"collections": "All",
"typeDistFile": "./apps/web/src/generated/tokens.ts"
}
}
}

Global fields​

FieldTypeDefaultNotes
baseLocalestringrequiredThe authoring locale. init writes en unless told otherwise.
localesstring[][]All supported locales. Include the base locale. Bundles are generated for this list only, so a locale added to a single collection with add-locale must also be added here before it can be bundled.
exportFolderstringdist/lingo-exportDefault output folder for export.
importFolderstringdist/lingo-importFolder the UI's Import dialog lists. The CLI import takes an explicit --source.
tokenCasing"upperCase" or "camelCase"upperCaseDefault casing for generated TypeScript keys. Overridable per bundle and by the --token-casing flag.
runtime"transloco-messageformat" or "transloco"transloco-messageformatHow the app renders bundles. Global only. Import and bundle both read it. Under transloco, a single { or ' is literal text: import quotes it in storage and bundle unquotes it. Values with ICU plural, select or similar are still bundled in messageformat form, with a warning. init detects it from package.json (dependencies and devDependencies only, not peerDependencies, so a library repo should pass --runtime); any other value fails every command.
transformICUToTranslocobooleantrueConvert {name} to {{ name }} in bundles. Overridable per bundle. With false, bundles hold stored ICU and runtime has no effect on them.
protectedTermsFilestring.lingo-tracker-protected-terms.jsonPath to the global protected-terms file, resolved against the config directory.
preferredTerminologyFilestring.lingo-tracker-preferred-terminology.jsonPath to the preferred-terminology rule file. Global only.
translationobjectnoneMachine translation settings, see below.
collectionsobjectrequiredCollection name to collection entry.
bundlesobjectinit creates mainBundle name to bundle definition.

Locale codes must match language or language-region with two to four letters in the region, such as en, fr-ca or zh-hans, case-insensitive. Codes with three subtags, such as zh-Hant-TW, or numeric regions, such as es-419, are rejected by add-locale and the collection dialog. init --locales and hand edits are not validated.

Collection entry​

FieldTypeInheritance
translationsFolderstringRequired. Resolved against the config directory.
baseLocalestringCollection value, else global.
localesstring[]Collection value when non-empty, else global. An empty array means inherit.
translationobjectReplaces the global block entirely. It is not merged, so a per-collection override must repeat provider and apiKeyEnv. { "enabled": false } alone is valid only because a disabled block is never used.
readOnlybooleantrue blocks every write to the collection's resources. Set automatically by add-collection for paths under node_modules.
tagsstring[]Tags every resource in the collection inherits. Normalized on read.
protectedTermsFilestringThe collection's own protected-terms file. No default. Its terms are added to the global ones.
exportFolder, importFolderstringStored, but only importFolder is used, by the UI's Import dialog. Export always uses the global folder or --output.

baseLocale, locales, exportFolder and importFolder are omitted from the entry when they equal the global value. A translation block is stored as supplied. To clear a field through the API or UI, send "", [] or false; the field is then removed and the collection inherits the global value again. A translation override cannot be cleared that way; edit the file.

Fields that cannot be set per collection: bundles, tokenCasing, transformICUToTransloco, preferredTerminologyFile.

Translation block​

"translation": {
"enabled": true,
"provider": "google-translate",
"apiKeyEnv": "GOOGLE_TRANSLATE_API_KEY",
"batchSize": 5,
"delayMs": 1000
}
FieldDefaultNotes
enabledfalse turns the feature off without deleting the block.
providerOnly google-translate is implemented. Any other value errors at translation time.
apiKeyEnvName of the environment variable that holds the key. The key itself never goes in the file.
batchSize5Resources per provider request when translating many resources.
delayMs1000Pause between those batches.

See Auto-Translation.

Bundle definition​

"web": {
"bundleName": "{locale}",
"dist": "./apps/web/src/assets/i18n",
"collections": [
{
"name": "main",
"bundledKeyPrefix": "web",
"entriesSelectionRules": [
{ "matchingPattern": "apps.web.*", "matchingTags": ["ui"], "matchingTagOperator": "All" }
],
"mergeStrategy": "merge"
}
],
"typeDistFile": "./apps/web/src/generated/tokens.ts",
"tokenCasing": "camelCase",
"tokenConstantName": "WEB_TOKENS",
"transformICUToTransloco": true
}
FieldRequiredNotes
bundle keyLetters, digits, - and _. Used by bundle --name and to derive the default constant name.
bundleNameyesFile name pattern. Must contain {locale}. {locale}/main writes one folder per locale.
distyesOutput folder, relative to the project root.
collectionsyes"All", or an ordered list of collection selections. The same collection can appear twice only with different bundledKeyPrefix values.
collections[].nameyesA collection name from collections.
collections[].bundledKeyPrefixPrefix added to every key from this collection.
collections[].entriesSelectionRulesyes"All", or a list of rules. An entry is included when any rule matches.
rule matchingPatternyes* for every key, prefix.* for a key and everything under it, or an exact key.
rule matchingTagsLowercase tags. ["*"] means "has any tag".
rule matchingTagOperatorAny (default) or All.
collections[].mergeStrategymerge (default): an earlier collection's value wins. override: this collection's value replaces earlier ones.
typeDistFileA .ts path. Enables TypeScript key generation.
tokenCasingOverrides the global value for this bundle.
tokenConstantNameA valid JavaScript identifier. Default is the bundle key upper-cased, hyphens turned into underscores, with _TOKENS appended: core-ui gives CORE_UI_TOKENS.
transformICUToTranslocoOverrides the global value for this bundle.

Precedence for tokenCasing and transformICUToTransloco: CLI flag, then bundle, then global, then default.

See Bundling and Bundle Type Generation.

Terminology files​

Both files are optional and are created on the first --add.

.lingo-tracker-protected-terms.json is a JSON array of strings, kept sorted:

["Acme", "iPhone", "Node.js"]

.lingo-tracker-preferred-terminology.json is a JSON array of rules, kept sorted by discouraged term:

[
{ "discouraged": "E-mail", "preferred": "email" },
{ "discouraged": "Expenditure", "preferred": "Investment", "reason": "Current planning term." }
]

See Protected Terms and Preferred Terminology.

Environment variables​

VariableUsed byPurpose
the name in translation.apiKeyEnvCLI, APIMachine translation API key
LINGO_TRACKER_PORTlingo-tracker-appListening port, default 3030. The --port flag wins.
LINGO_TRACKER_HOSTlingo-tracker-appBind address, default 127.0.0.1. The --host flag wins.
LINGO_TRACKER_ALLOWED_HOSTSlingo-tracker-appComma-separated host names accepted in the Host header besides localhost and IP literals. A port in an entry is ignored.
LINGO_TRACKER_REVALIDATE_INTERVAL_MSlingo-tracker-appHow often the in-memory index checks the disk for outside changes, default 2000.
LINGO_TRACKER_MAX_CACHED_COLLECTIONSlingo-tracker-appCollections kept indexed in memory, default 4.
INIT_CWDCLISet by package managers. When present, the CLI uses it as the project root, so pnpm lingo-tracker … works from the directory you typed it in.

Generated and ignorable files​

Commit .lingo-tracker.json, the terminology files and every translations folder. Bundle output and the generated token file are build artifacts; most projects generate them in a prebuild step and list them in .gitignore. Exports and imports default to dist/, which is normally ignored already.