CLI Reference

This document provides a comprehensive reference for all Lingo Tracker CLI commands. For initial setup instructions, see the Getting Started Guide.

Overview

The Lingo Tracker CLI provides commands to manage translation collections and resources from the command line. All commands support both interactive mode (with prompts) and non-interactive mode (for CI/CD environments).

General Usage

lingo-tracker <command> [options]

Interactive vs Non-Interactive Mode

Interactive Mode: When running in a TTY environment without all required options, the CLI will prompt you for missing values.
Non-Interactive Mode: In CI/CD environments or when all required options are provided, no prompts will appear.

Common Options

Most commands accept configuration options that can override defaults from .lingo-tracker.json
Options use --kebab-case naming convention
Multi-value options (like --locales) accept space-separated values

Collection Commands

init

Initialize a new Lingo Tracker project by creating a .lingo-tracker.json configuration file.

Usage:

lingo-tracker init [options]

Options:

--collection-name <name> - Name of the initial collection key, e.g., "Main" (required in non-interactive mode)
--translations-folder <path> - Path to the translations directory for this collection (required in non-interactive mode)
--export-folder <path> - Output folder for exports (default: dist/lingo-export)
--import-folder <path> - Input folder for imports (default: dist/lingo-import)
--base-locale <locale> - Base/authoring locale (default: en)
--locales <locales...> - Space-separated list of supported locales (e.g., en fr-ca es de)

Bundle options:

--setup-bundle <true|false> - Customize bundle configuration (default: prompted interactively). When omitted and any bundle flag is provided, automatically inferred as true
--bundle-dist <path> - Bundle output directory (default: ./src/assets/i18n)
--bundle-name <pattern> - Bundle name pattern (default: {locale})
--token-casing <casing> - Token property key casing: upperCase or camelCase
--type-dist-file <path> - Path for generated TypeScript type definitions file (default: ./src/generated/tokens.ts)
--token-constant-name <name> - Custom name for the generated TypeScript constant (auto-derived from bundle key when omitted)

Auto-translation options:

--enable-auto-translation - Enable automatic translation via an external provider
--translation-provider <provider> - Translation provider to use (default: google-translate). Required when --enable-auto-translation is set
--translation-api-key-env <envVar> - Name of the environment variable holding the provider API key (default: GOOGLE_TRANSLATE_API_KEY). Required when --enable-auto-translation is set

Examples:

Interactive mode (prompts for values):

lingo-tracker init

Non-interactive mode (CI-safe, all required options provided):

lingo-tracker init \
  --collection-name Main \
  --translations-folder apps/web/src/assets/i18n \
  --export-folder dist/lingo-export \
  --import-folder dist/lingo-import \
  --base-locale en \
  --locales en fr-ca es de

Non-interactive mode with bundle configuration:

lingo-tracker init \
  --collection-name Main \
  --translations-folder apps/web/src/assets/i18n \
  --base-locale en \
  --locales en fr-ca es de \
  --setup-bundle true \
  --bundle-dist ./src/assets/i18n \
  --bundle-name "{locale}" \
  --token-casing camelCase \
  --type-dist-file ./src/generated/tokens.ts

Non-interactive mode with auto-translation enabled:

lingo-tracker init \
  --collection-name Main \
  --translations-folder apps/web/src/assets/i18n \
  --base-locale en \
  --locales en fr-ca es de \
  --enable-auto-translation \
  --translation-provider google-translate \
  --translation-api-key-env GOOGLE_TRANSLATE_API_KEY

Notes:

Run this command once in your project root to create .lingo-tracker.json
Creates the initial configuration with one collection and a default bundle
In interactive mode, you will be prompted to customize the bundle configuration (dist path, name pattern, token casing, type generation)
If you decline bundle customization, a default bundle is still created with dist: ./src/assets/i18n, bundleName: {locale}, and collections: All
Commit .lingo-tracker.json to version control
When --enable-auto-translation is set, the translation block is written to .lingo-tracker.json and new/edited resources are automatically translated via the configured provider

add-collection

Add a new translation collection to an existing Lingo Tracker project. Collections allow you to manage multiple translation sources within the same repository (e.g., main app, admin panel, mobile app).

Usage:

lingo-tracker add-collection [options]

Options:

--collection-name <name> - Name of the new collection (required in non-interactive mode)
--translations-folder <path> - Path to the translations directory for this collection (required in non-interactive mode)
--export-folder <path> - Override global export folder for this collection
--import-folder <path> - Override global import folder for this collection
--base-locale <locale> - Override global base locale
--locales <locales...> - Override global locales list
--read-only - Mark the collection as read-only (its resources cannot be modified)
--no-read-only - Force the collection writable, overriding node_modules auto-detection

Examples:

Interactive mode (prompts for collection details, including a read-only confirmation):

lingo-tracker add-collection

Simple, using global defaults:

lingo-tracker add-collection \
  --collection-name Admin \
  --translations-folder apps/admin/src/assets/i18n

With collection-specific overrides (only differences are saved):

lingo-tracker add-collection \
  --collection-name Mobile \
  --translations-folder apps/mobile/src/i18n \
  --base-locale en-GB

lingo-tracker add-collection \
  --collection-name DesignSystem \
  --translations-folder node_modules/@acme/design-system/i18n \
  --read-only

Notes:

Requires an existing .lingo-tracker.json configuration file (run init first)
Reuses global defaults; only saves overrides when they differ
Will refuse to add a collection if the name already exists
Only persists per-collection settings that differ from global configuration

Read-only collections:

A collection can be marked read-only via the readOnly flag on its config entry. When true, the CLI, API, and web UI refuse to modify its resources — add-resource, edit-resource, delete-resource, move, normalize, import, add-locale, remove-locale, and translate-locale are all blocked (the CLI exits with a non-zero status so CI fails). Read-only commands (bundle, export, validate, find-similar, glossary) are unaffected.
normalize --all is the one exception: it skips read-only collections with an informational message and does not fail the run (so bulk normalization stays green even when a vendored read-only collection is present). Targeting a read-only collection explicitly (normalize --collection <name>) still fails.
The lock protects a collection's resources, not its registration: you can still delete-collection (unregister it) and edit its config entry — including turning readOnly off.
When the --translations-folder is under node_modules, read-only defaults to true (in interactive mode the prompt is pre-checked; in non-interactive mode pass --no-read-only to override). This is convenient for component-library collections vendored into a consumer repo, which should not be edited locally.
The stored readOnly flag is the single source of truth. A node_modules path only sets the default at add time — it never forces read-only at runtime, and existing collections are never auto-migrated.

edit-collection

Edit an existing collection's configuration. Currently supports managing collection-level tags that are inherited by all resources in the collection.

Usage:

lingo-tracker edit-collection <name> [options]

Options:

--add-tag <tag> - Add a tag to the collection's tag list (repeatable, normalized automatically)
--remove-tag <tag> - Remove a tag from the collection's tag list (repeatable)
--set-tags <a,b,c> - Replace the entire tag list with a comma-separated set; pass "" to clear all tags (mutually exclusive with --add-tag/--remove-tag)

Examples:

Add a tag:

lingo-tracker edit-collection myApp --add-tag team-x

Remove a tag:

lingo-tracker edit-collection myApp --remove-tag team-x

Add multiple tags at once:

lingo-tracker edit-collection myApp --add-tag team-x --add-tag mobile

Replace all tags:

lingo-tracker edit-collection myApp --set-tags "team-x,mobile,legal"

Clear all tags:

lingo-tracker edit-collection myApp --set-tags ""

Notes:

--set-tags and --add-tag/--remove-tag are mutually exclusive
Tags are normalized automatically (lowercase, hyphens, max 50 chars)
Collection-level tags are inherited by every resource in the collection at read time; they are not written into resource_entries.json files
These tags are respected by export --tags, bundle filtering, and the Tracker UI

delete-collection

Delete a translation collection from the project.

Usage:

lingo-tracker delete-collection [options]

Options:

--collection-name <name> - Name of the collection to delete (required in non-interactive mode)

Examples:

Interactive mode (prompts for collection):

lingo-tracker delete-collection

Non-interactive mode:

lingo-tracker delete-collection --collection-name Mobile

Notes:

Removes the collection entry from .lingo-tracker.json
Does NOT delete translation files from disk (data is preserved)
Will prompt for confirmation before deletion (in interactive mode)

add-locale

Add a locale to a collection and backfill all existing resources with the new locale.

Usage:

lingo-tracker add-locale [options]

Options:

--collection <name> - Name of the collection (required in non-interactive mode)
--locale <locale> - Locale to add, e.g. fr-ca, de, es (required in non-interactive mode)

Examples:

Interactive mode (prompts for collection and locale):

lingo-tracker add-locale

Non-interactive mode:

lingo-tracker add-locale --collection Main --locale de

Notes:

Validates locale format (e.g. en, fr-ca, zh-Hans)
Errors if the locale already exists in the collection
Cannot add the base locale
If the collection inherits global locales (no explicit locales in its config), global locales are copied into the collection first, then the new locale is appended
All existing resource_entries.json files are updated with the new locale value set to the base (source) value, and tracker_meta.json is updated with status: "new"

remove-locale

Remove a locale from a collection and purge all of its translation data from resource files.

Usage:

lingo-tracker remove-locale [options]

Options:

--collection <name> - Name of the collection (required in non-interactive mode)
--locale <locale> - Locale to remove (required in non-interactive mode)

Examples:

Interactive mode (prompts for collection, then shows a list of removable locales):

lingo-tracker remove-locale

Non-interactive mode:

lingo-tracker remove-locale --collection Main --locale de

Notes:

Errors if the locale does not exist in the collection
Cannot remove the base locale
Removes the locale key from all resource_entries.json and tracker_meta.json files in the collection
Translation data for the locale is permanently deleted from files (recoverable via git)
Removing the last non-base locale is allowed (results in a monolingual collection)
If the collection inherits global locales, global locales are copied into the collection first, then the target locale is removed

Resource Commands

add-resource

Add a translation resource to a collection.

Usage:

lingo-tracker add-resource [options]

Options:

--collection <name> - Collection to add the resource to (required in non-interactive mode)
--key <key> - Dot-delimited resource key, e.g., apps.common.buttons.ok (required in non-interactive mode)
--value <text> - Base (source) text in the base locale (required in non-interactive mode)
--comment <text> - Optional context for translators
--tags <tags> - Optional comma-separated tags for filtering/exporting. Values are normalized on write: lowercased, whitespace replaced with hyphens, non-[a-z0-9-] characters stripped, max 50 chars.
--target-folder <folder> - Optional dot-delimited path override for folder placement
--translations <json> - Optional JSON array with translation objects

Translation Object Format:

The --translations option accepts a JSON array of objects with the following structure:

[
  {
    "locale": "es",
    "value": "Aplicar",
    "status": "translated"
  },
  {
    "locale": "fr-ca",
    "value": "Appliquer",
    "status": "verified"
  }
]

Valid status values: new, translated, verified, stale

Examples:

Interactive mode (prompt for all values):

lingo-tracker add-resource

Non-interactive, minimal (key placed directly in translation folder):

lingo-tracker add-resource \
  --collection Main \
  --key buttons.ok \
  --value OK

Non-interactive, full options (key nested under apps.common, tagged, with translations):

lingo-tracker add-resource \
  --collection Main \
  --key buttons.ok \
  --value OK \
  --comment "OK button in dialogs" \
  --tags "ui,buttons,dialogs" \
  --target-folder apps.common \
  --translations '[{"locale":"es","value":"Aceptar","status":"translated"},{"locale":"fr-ca","value":"OK","status":"new"}]'

Notes:

In interactive mode, you'll be prompted if you want to provide translations for each configured locale
Resources are placed in the appropriate folder based on the key and optional --target-folder
If a translation's checksum matches the base value's checksum, the status will automatically be set to new regardless of the provided status

delete-resource

Delete one or more translation resources from a collection.

Usage:

lingo-tracker delete-resource [options]

Options:

--collection <name> - Collection to delete resources from (required in non-interactive mode)
--key <keys> - Resource key(s) - single key or comma-separated (required in non-interactive mode)
--yes - Skip confirmation prompt (useful for scripts)

Examples:

Interactive mode (prompts for collection and key):

lingo-tracker delete-resource

Delete a single resource:

lingo-tracker delete-resource \
  --collection Main \
  --key apps.common.buttons.ok

Delete multiple resources (comma-separated):

lingo-tracker delete-resource \
  --collection Main \
  --key "apps.common.buttons.ok,apps.common.buttons.cancel,apps.common.buttons.save"

Skip confirmation prompt (useful for scripts):

lingo-tracker delete-resource \
  --collection Main \
  --key apps.common.buttons.ok \
  --yes

Behavior:

Bulk Operations: The command uses a best-effort approach. If some keys fail validation or are not found, the operation continues processing remaining keys and reports the count of successful deletions.
File Cleanup: When the last resource entry is deleted from a folder, both resource_entries.json and tracker_meta.json are removed. Empty parent folders are preserved (keeps Git structure stable).
Confirmation: In interactive mode (TTY), you'll be asked to confirm the deletion unless the --yes flag is provided. The confirmation shows all keys that will be deleted.
Partial Success: If some keys succeed and others fail, the command completes successfully and reports both the deletion count and any errors encountered.

Output:

# Successful deletion
✅ Deleted 3 resource(s)

# Partial success with errors
✅ Deleted 2 resource(s)

⚠️  Some operations failed:
   - invalid..key: Invalid key format
   - nonexistent.key: Resource not found

Notes:

This command removes translations for ALL locales for the specified keys
In non-interactive mode, you must provide all required options
Errors for individual keys don't halt the operation; other keys continue to be processed

edit-resource

Edit an existing translation resource.

Usage:

lingo-tracker edit-resource [options]

Options:

--collection <name> - Collection containing the resource (required in non-interactive mode)
--key <key> - Resource key (required in non-interactive mode)
--base-value <text> - New base value (updates source text)
--comment <text> - New comment
--tags <tags> - New tags (comma-separated, replaces existing). Values are normalized on write: lowercased, whitespace replaced with hyphens, non-[a-z0-9-] characters stripped, max 50 chars.
--target-folder <folder> - New target folder
--locale <locale> - Locale to update (requires --locale-value)
--locale-value <text> - New translation value for the specified locale

Examples:

Interactive mode:

lingo-tracker edit-resource

Update base value (marks other locales as stale):

lingo-tracker edit-resource \
  --collection Main \
  --key buttons.save \
  --base-value "Save Item"

Update a specific translation:

lingo-tracker edit-resource \
  --collection Main \
  --key buttons.save \
  --locale fr-ca \
  --locale-value "Enregistrer l'article"

Update metadata:

lingo-tracker edit-resource \
  --collection Main \
  --key buttons.save \
  --comment "Main save button" \
  --tags "ui,primary"

Notes:

Updating --base-value triggers a checksum update and marks all other existing translations as stale.
Updating a locale value sets its status to translated and updates its checksum.
If no changes are detected (values match existing), the command reports "No changes detected".

translate-locale

Auto-translate all new and stale resources in a collection for a single target locale. Requires auto-translation to be enabled in .lingo-tracker.json.

Usage:

lingo-tracker translate-locale [options]

Options:

--collection <name> - Collection name (prompted if not provided)
--locale <locale> - Target locale to translate (prompted if not provided)
--verbose - Show per-batch progress (default: summary only)

Interactive mode:

When running in a TTY environment without --collection or --locale, the command prompts for the missing values.

Non-interactive mode:

Both --collection and --locale are required. The command exits with a non-zero code if either is missing.

Examples:

Interactive mode (prompts for collection and locale):

lingo-tracker translate-locale

Non-interactive mode:

lingo-tracker translate-locale \
  --collection Main \
  --locale fr

With verbose progress:

lingo-tracker translate-locale \
  --collection Main \
  --locale fr \
  --verbose

Output (summary mode):

Translating locale 'fr' in collection 'playground'...
Done.

Translated: 45 resources
Skipped (ICU): 3 resources
Failed: 0 resources

Output (verbose mode):

[batch 1/9] translated: 5, skipped: 0, failed: 0
[batch 2/9] translated: 10, skipped: 0, failed: 0
...

Notes:

Only resources with status new or stale are translated; translated and verified resources are left unchanged
Resources whose base value uses complex ICU syntax are skipped and reported in the "Skipped (ICU)" count
Throttling is controlled by batchSize and delayMs in the translation config block; see Auto-Translation for recommended settings
Requires translation.enabled: true in .lingo-tracker.json

move

Move or rename translation resources. Supports moving single resources as well as bulk moves using wildcard patterns.

Usage:

lingo-tracker move [options]

Options:

--collection <name> - Collection to move resources in (required in non-interactive mode)
--source <key> - Source key or pattern (e.g., common.buttons.ok or common.buttons.*) (required in non-interactive mode)
--dest <key> - Destination key (e.g., common.actions.ok or common.actions) (required in non-interactive mode)
--override - Overwrite destination if it already exists
--verbose - Print detailed output for each moved resource

Examples:

Interactive mode:

lingo-tracker move

Move a single resource:

lingo-tracker move \
  --collection Main \
  --source common.buttons.ok \
  --dest common.actions.ok

Move multiple resources using a wildcard pattern:

lingo-tracker move \
  --collection Main \
  --source "common.buttons.*" \
  --dest "common.actions"

Result: common.buttons.ok -> common.actions.ok, common.buttons.cancel -> common.actions.cancel

Force move (overwrite destination):

lingo-tracker move \
  --collection Main \
  --source old.key \
  --dest new.key \
  --override

Notes:

When using wildcard patterns, the suffix matched by * is appended to the destination key.
Moving a resource preserves its comments, tags, and translations.
The source resource is deleted after a successful move.

normalize

Normalize translation resources by recomputing checksums, adding missing locale entries, updating statuses, and cleaning up empty folders. This is a maintenance operation that ensures translation files are consistent and correct after manual edits, configuration changes, or imports.

Usage:

lingo-tracker normalize [options]

Options:

--collection <name> - Collection name to normalize (required unless --all is used)
--all - Normalize all collections in the project
--dry-run - Preview changes without applying them (reports what would be changed)
--json - Output results as JSON (useful for scripts and automation)

What Normalization Does:

Recomputes checksums: Updates MD5 checksums for base locale and all translations
Adds missing locales: Creates entries for any missing locales using the base value with status new
Updates statuses: Sets correct translation status based on checksums
- new - Locale entry was just added or matches base value
- stale - Base value changed since last translation (checksum mismatch)
- translated / verified - Preserved when base value unchanged
Normalizes tags: Coerces all tag values to lowercase, hyphenated form ([a-z0-9-], max 50 chars). For example "Common UI" → "common-ui". Deduplicates tags within each resource. This is the recommended way to clean up legacy tag data that pre-dates strict validation.
Creates missing files: Ensures resource_entries.json and tracker_meta.json exist at every folder level
Cleans up empty folders: Removes folders with no entries (bottom-up recursive cleanup)

Folder Cleanup Behavior:

Normalization automatically removes empty folders to keep the translations directory clean:

Folders are considered empty if they contain:
- No resource_entries.json file, OR
- An empty resource_entries.json (no entries or {}), AND
- No subfolders
Folders containing only tracker_meta.json or hidden files (.gitkeep, .DS_Store) are removed
Cleanup uses bottom-up traversal (deepest folders first) to handle recursive removal
The root translations folder is never removed, even if empty

When to Use Normalize:

After manually editing JSON translation files
After adding new locales to configuration
After importing translations from external sources
Periodically to maintain consistency and clean up the folder structure
When translation statuses seem incorrect

Examples:

Interactive mode (prompts for collection):

lingo-tracker normalize

Normalize a specific collection:

lingo-tracker normalize --collection Main

Normalize all collections:

lingo-tracker normalize --all

Preview changes without applying (dry-run):

lingo-tracker normalize --collection Main --dry-run

Output results as JSON (useful for scripts):

lingo-tracker normalize --collection Main --json

Normalize all collections with JSON output:

lingo-tracker normalize --all --json

Output:

Human-readable format (default):

🔄 Normalizing collection: Main

   ✅ Entries processed: 42
   ✅ Locales added: 7
   ✅ Values converted to ICU: 0
   ✅ Tags normalized: 5
   ✅ Files created: 2
   ✅ Files updated: 15
   ✅ Folders removed: 3

Note: "Tags normalized" only appears when at least one tag was coerced.

JSON format (--json flag):

{
  "collections": [
    {
      "collectionName": "Main",
      "entriesProcessed": 42,
      "localesAdded": 7,
      "valuesConverted": 0,
      "tagsNormalized": 5,
      "filesCreated": 2,
      "filesUpdated": 15,
      "foldersRemoved": 3
    }
  ],
  "totals": {
    "collectionsProcessed": 1,
    "entriesProcessed": 42,
    "localesAdded": 7,
    "valuesConverted": 0,
    "tagsNormalized": 5,
    "filesCreated": 2,
    "filesUpdated": 15,
    "foldersRemoved": 3
  }
}

Notes:

Normalization is non-destructive: it preserves existing translation values and comments
Tag values are coerced to normalized form (lowercase, hyphens, max 50 chars) — this is the intended cleanup path for legacy tags
Only fills in missing data and corrects metadata
Dry-run mode counts folders that would be removed but doesn't delete them
In interactive mode, you'll be prompted to confirm when using --all
Best practice: run with --dry-run first to preview changes before applying

bundle

Generate translation bundles for deployment.

Usage:

lingo-tracker bundle [options]

Options:

--name <names> - Bundle name(s) to generate (comma-separated). If not specified, generates all configured bundles
--locale <locales> - Specific locale(s) to generate (comma-separated). If not specified, generates all locales
--token-casing <casing> - Casing style for generated type token keys: upperCase or camelCase. Overrides any tokenCasing set in the config file. Default: upperCase
--token-constant-name <name> - Custom name for the generated TypeScript constant. Must be a valid JavaScript identifier. Only works when targeting a single bundle (via --name). Overrides tokenConstantName in the bundle config
--no-transform-icu-to-transloco - Disable ICU to Transloco format conversion in bundle output
--debug-keys [locale] - Also emit a debug bundle where every value equals its own dot-delimited key. Useful for visually locating untranslated strings at runtime by switching your app to this locale. If no locale code is provided, defaults to 99 (e.g. main.99.json). ICU transformation is skipped for the debug bundle.
--verbose - Show detailed output including all warnings

What Bundle Generation Does:

Reads bundle configuration from .lingo-tracker.json bundles section
Collects translations from specified collections based on selection rules
Applies filters using pattern matching and tag-based selection
Resolves conflicts using merge strategies (merge or override)
Transforms to hierarchical JSON (flat keys → nested objects)
Writes bundle files to configured output directories with {locale} placeholder replacement

When to Use Bundle:

Before deploying your application to production
As part of your build pipeline
After translator completes translations
When you need to generate bundles for specific locales only
To preview bundle contents with --verbose flag

Examples:

Interactive mode (prompts for bundle selection):

lingo-tracker bundle

Generate all configured bundles:

lingo-tracker bundle

Generate specific bundle(s):

lingo-tracker bundle --name core
lingo-tracker bundle --name core,admin

Generate bundles for specific locale(s):

lingo-tracker bundle --locale en,fr

Verbose output (shows all warnings):

lingo-tracker bundle --verbose

Combined options:

lingo-tracker bundle --name core --locale en,fr --verbose

Override token casing for generated types:

lingo-tracker bundle --token-casing camelCase

Custom constant name for a single bundle:

lingo-tracker bundle --name core --token-constant-name MY_KEYS

Generate debug bundle with default locale 99:

lingo-tracker bundle --debug-keys

Generate debug bundle with a custom locale code:

lingo-tracker bundle --debug-keys debug

Output:

Normal output (default):

🔄 Generating bundle: core

   ✅ Files generated: 3
   ✅ Locales: en, fr-ca, es
   ⚠️  Warnings: 2

Verbose output (--verbose flag):

🔄 Generating bundle: core
   Locales: en, fr-ca

   ✅ Files generated: 2
   ✅ Locales: en, fr-ca
   ⚠️  Warnings: 1
      - Bundle 'core' for locale 'es' is empty

Summary for multiple bundles:

🔄 Generating bundle: core

   ✅ Files generated: 3
   ✅ Locales: en, fr-ca, es

🔄 Generating bundle: admin

   ✅ Files generated: 3
   ✅ Locales: en, fr-ca, es

📊 Summary (2 bundles):
   Total files generated: 6

Bundle Configuration:

Bundles are configured in .lingo-tracker.json:

{
  "tokenCasing": "upperCase",
  "bundles": {
    "main": {
      "bundleName": "{locale}",
      "dist": "./dist/i18n",
      "collections": "All"
    },
    "admin": {
      "bundleName": "admin-{locale}",
      "dist": "./dist/admin/i18n",
      "tokenCasing": "camelCase",
      "collections": [
        {
          "name": "Admin",
          "entriesSelectionRules": "All"
        }
      ]
    },
    "core": {
      "bundleName": "resources.{locale}",
      "dist": "./src/assets/i18n",
      "collections": [
        {
          "name": "Common",
          "bundledKeyPrefix": "common",
          "entriesSelectionRules": [
            {
              "matchingPattern": "apps.common.*",
              "matchingTags": ["ui"],
              "matchingTagOperator": "All"
            }
          ],
          "mergeStrategy": "merge"
        }
      ]
    }
  }
}

Bundle Definition Fields:

bundleName - Output filename pattern (use {locale} placeholder for locale substitution)
dist - Output directory path (relative to project root)
tokenCasing (optional) - Casing style for generated type token keys: "upperCase" (default) or "camelCase". When set on a bundle, overrides the global tokenCasing. See Bundle Type Generation for details
tokenConstantName (optional) - Custom name for the generated TypeScript constant. Must be a valid JavaScript identifier. When omitted, derived from the bundle key (e.g., common → COMMON_TOKENS). See Bundle Type Generation for details
collections - Either "All" or array of collection definitions
- name - Collection name from config
- bundledKeyPrefix (optional) - Prefix to add to all keys from this collection
- entriesSelectionRules - Either "All" or array of selection rules
  - matchingPattern - Pattern to match keys: "*" (all), "apps.*" (wildcard), or exact key
  - matchingTags (optional) - Tags to filter by
  - matchingTagOperator (optional) - "All" (requires all tags) or "Any" (requires any tag, default)
- mergeStrategy (optional) - "merge" (first wins, default) or "override" (later wins)

Merge Strategies:

When multiple collections contribute the same key:

merge (default): First collection wins - key from earlier collection is kept
override: Later collection wins - key from later collection overwrites previous

Pattern Matching:

"*" - Matches all keys
"apps.*" - Matches apps and all keys starting with apps.
"apps.common.buttons.ok" - Exact match only

Tag Filtering:

matchingTags: ["ui"] with matchingTagOperator: "Any" - Entry must have ui tag
matchingTags: ["ui", "buttons"] with matchingTagOperator: "All" - Entry must have both tags
matchingTags: ["*"] - Entry must have at least one tag (any tag)

Notes:

Bundle generation is read-only: it never modifies source translation files
Empty bundles (no matching entries) generate a warning but don't create files
Base locale translations use the source property; other locales use their locale key
Warnings include empty bundles, missing collections, and missing translations
For detailed examples and integration guides, see Bundling Guide

Search Commands

find-similar

Find existing translation resources whose base locale value is similar to a given string. Useful for detecting duplicate or near-duplicate translations before adding a new resource.

Usage:

lingo-tracker find-similar [options]

Options:

--collection <name> - Collection to search (required)
--value <text> - Base locale text to compare against (required)
--max-results <n> - Maximum number of results to return (default: 5)

Examples:

Find resources similar to "Save":

lingo-tracker find-similar \
  --collection Main \
  --value "Save"

Limit results:

lingo-tracker find-similar \
  --collection Main \
  --value "Are you sure you want to delete this item?" \
  --max-results 3

Output:

When matches are found:

Similar values found for "Save":
  buttons.save → "Save" (similarity: 100%)
  buttons.saveAndClose → "Save and Close" (similarity: 89%)

When no matches meet the similarity threshold:

No similar values found for "Save draft".

How It Works:

Runs a broad substring pre-filter via searchTranslations (up to 50 candidates)
Scores each candidate using normalised Levenshtein distance (case-insensitive)
Keeps only results with a similarity score ≥ 80%
Returns top N results sorted by score descending

Notes:

Only the base locale value is compared (not translations)
Only exact-value and partial-value match types are considered; key-based matches are excluded
Similarity threshold is fixed at 80% — results below this are not shown
Non-interactive only; does not prompt for missing options

glossary

Extract a glossary of relevant translations from a block of text. Given a paragraph of base-locale text (for example a page of online help), the command pulls out the meaningful terms, finds the matching translation entries, and writes a JSON glossary containing each term's translations across all locales. The glossary can then be handed to whoever (or whatever) translates the help content so they reuse the app's existing terminology.

Usage:

lingo-tracker glossary [options]

Options:

--text <text> - Inline text block to extract terms from
--input <file> - Path to a file whose contents are the input text block
--output <file> - Output JSON file path (default: ./lingo-tracker-glossary-<timestamp>.json)
--stdout - Print the glossary JSON to stdout instead of writing a file (status messages go to stderr)
--collection <name> - Limit matching to a single collection (default: all collections)
--locales <list> - Comma-separated locales to include (default: all configured locales)
--include-all - Include new/stale entries (default: only translated + verified)
--extractor <mode> - Term extraction strategy: ngram (default). ai is reserved for a future release.

Input precedence is --text → --input → piped stdin.

Examples:

From a file:

lingo-tracker glossary --input help-page.md

Inline snippet, French only, printed to stdout:

lingo-tracker glossary --text "Click Save in Settings to update your profile" --locales fr --stdout

Piped from another command:

cat help-page.md | lingo-tracker glossary --stdout | jq '.terms[].key'

Output:

{
  "baseLocale": "en",
  "locales": ["fr", "es"],
  "source": { "chars": 1234, "candidates": 18 },
  "matchCount": 2,
  "terms": [
    {
      "key": "apps.common.buttons.save",
      "collection": "app",
      "base": "Save",
      "matchedTerm": "save",
      "score": 1.0,
      "translations": { "fr": "Enregistrer", "es": "Guardar" },
      "status": { "fr": "verified", "es": "translated" }
    }
  ]
}

How It Works:

Extract — the block is split into sentences and tokenized; stopwords and very short tokens are dropped, leaving content-word unigrams and bigrams as candidate terms.
Match — each candidate is matched against entries' base-locale values only (key names are ignored). Scoring: exact value match (1.0) beats whole-word/phrase containment.
Rank — the single best entry per candidate is kept; an entry matched by several candidates appears once (highest score wins). Results are sorted by score.
Filter & write — only translated/verified locales are included by default (--include-all adds new/stale); each collection's base locale is omitted from translations since it appears as base.

Notes:

Matching is deterministic and value-only — no fuzzy matching, which keeps the glossary precise (favouring precision over recall).
The extractor is a swappable stage: the --extractor flag reserves room for a future AI-based extractor.
The stopword list is English-oriented, so extraction is weaker when the base locale is not English.

Validation Commands

validate

Validate translation completeness and readiness for production release. This command checks all resources across all locales and collections, ensuring translations meet quality standards before deployment.

Usage:

lingo-tracker validate [options]

Options:

--allow-translated - Treat 'translated' status as warning instead of failure (default: false)
--skip-locales <locales> - Comma-separated list of locales to exclude from validation (e.g. fr or fr,de). Useful when a locale has been added to the config but its translations are still in progress. Unknown locales (not in config.locales) emit a warning and are ignored. The base locale is silently ignored. If all target locales are skipped, the command exits with code 1.

What Validate Does:

Loads all resources from all configured collections
Checks translation status for every resource in every target locale
Collects all validation results (does not stop at first error)
Categorizes findings into failures, warnings, and successes
Reports comprehensive results grouped by locale

Validation Rules:

Status	Default Behavior	With `--allow-translated`
`new`	❌ Failure	❌ Failure
`stale`	❌ Failure	❌ Failure
`translated`	❌ Failure	⚠️ Warning
`verified`	✅ Success	✅ Success

Exit Codes:

0 - All validations passed (all resources verified)
1 - Validation failures found (new/stale resources or translated without --allow-translated flag)

When to Use Validate:

As a quality gate in CI/CD pipelines before release
Before deploying to production environments
To verify all translations are complete and verified
To enforce translation quality standards in automated builds
During staging deployments (with --allow-translated for relaxed requirements)

Examples:

Strict validation (production):

lingo-tracker validate

Output on failure:

❌ Translation Validation FAILED

Validation Summary by Locale:
  es:
    new: 3
    stale: 2
    translated: 1
    verified: 45

  fr-ca:
    new: 1
    stale: 0
    translated: 2
    verified: 48

Failures (6 resources):
  es:
    - apps.common.buttons.submit (new)
    - apps.common.errors.network (new)
    - apps.features.dashboard.title (new)
    - apps.common.buttons.save (stale)
    - apps.features.settings.label (stale)
    - apps.common.buttons.cancel (translated)

  fr-ca:
    - apps.common.buttons.submit (new)
    - apps.features.dashboard.subtitle (translated)
    - apps.features.profile.header (translated)

Total: 6 failures, 0 warnings

Relaxed validation (staging):

lingo-tracker validate --allow-translated

Output with warnings:

⚠️  Translation Validation PASSED with warnings

Validation Summary by Locale:
  es:
    new: 3
    stale: 2
    translated: 1
    verified: 45

  fr-ca:
    new: 1
    stale: 0
    translated: 2
    verified: 48

Failures (5 resources):
  es:
    - apps.common.buttons.submit (new)
    - apps.common.errors.network (new)
    - apps.features.dashboard.title (new)
    - apps.common.buttons.save (stale)
    - apps.features.settings.label (stale)

  fr-ca:
    - apps.common.buttons.submit (new)

Warnings (3 resources):
  es:
    - apps.common.buttons.cancel (translated)

  fr-ca:
    - apps.features.dashboard.subtitle (translated)
    - apps.features.profile.header (translated)

Total: 5 failures, 3 warnings

Skip a locale that is still in progress:

lingo-tracker validate --skip-locales fr
lingo-tracker validate --skip-locales fr,de

CI/CD Integration Examples:

GitHub Actions:

- name: Validate translations
  run: lingo-tracker validate

GitLab CI:

validate-translations:
  script:
    - lingo-tracker validate

Jenkins:

sh 'lingo-tracker validate'

CircleCI:

- run:
    name: Validate translations
    command: lingo-tracker validate

Staging pipeline (allow translated):

- name: Validate translations (staging)
  run: lingo-tracker validate --allow-translated

Comprehensive Validation:

The validate command performs a comprehensive check:

Validates ALL collections (no filtering)
Validates ALL target locales by default (excludes base locale)
Collects ALL validation results before reporting
Shows COMPLETE summary of all failures and warnings
Does NOT stop at first error

Notes:

Non-interactive only (designed for CI/CD, never prompts)
Validates all target locales by default (base locale is excluded)
Use --skip-locales to exclude specific locales; skipped locales appear in the validation summary
Unknown locale values in --skip-locales emit a warning and are ignored
Validates all collections (no collection filtering)
Reports all issues comprehensively before exiting
Exit code reflects overall validation status after checking everything
Use --allow-translated for staging deployments where not all translations may be verified yet

Data Exchange Commands

export

Export translation resources to XLIFF or JSON format for integration with translation services, external systems, and third-party tools.

Usage:

lingo-tracker export [options]

Options:

-f, --format <format> - Export format: xliff or json (required in non-interactive mode)
-c, --collection <names> - Specific collection(s) to export (comma-separated). If not specified, exports all collections
-l, --locale <locales> - Target locale(s) to export (comma-separated). If not specified, exports all target locales (excludes base locale)
-s, --status <statuses> - Filter by translation status (comma-separated). Default: new,stale
- Valid values: new, translated, stale, verified
-t, --tags <tags> - Filter by tags (comma-separated). Only resources with matching tags are included
-o, --output <path> - Output directory path. Default: from config exportFolder or dist/lingo-export
--filename <pattern> - Custom filename pattern with placeholders
--dry-run - Preview export without writing files (shows what would be exported)
--verbose - Show detailed export progress

JSON-Specific Options:

--structure <type> - JSON structure: hierarchical (nested objects) or flat (dot-delimited keys). Default: hierarchical
--rich - Include metadata in JSON objects (creates objects instead of string values). Default: false
--include-base - Include base locale value in the output object. Default: false
--include-status - Include translation status in the output object. Default: false
--include-comment - Include translator comments in the output object. Default: false
--include-tags - Include tags array in the output object. Default: false
--base-property-name <name> - Property name used for the base locale value in JSON output. Only applies with --include-base. Default: baseValue. The names value, comment, status, and tags are reserved and will cause an error.

Filename Placeholders:

Customize output filenames using these placeholders:

{locale} - Target locale code (e.g., es, fr-ca)
{target} - Alias for {locale}
{source} - Base locale code (e.g., en)
{date} - Current date in YYYY-MM-DD format

What Export Does:

Loads resources from specified collections
Filters resources by locale, status, and tags
Transforms data to target format (XLIFF or JSON)
Writes files to output directory (one file per locale)
Generates summary report with statistics, warnings, and errors

When to Use Export:

Sending translations to translation agencies (use XLIFF format)
Integrating with Translation Management Systems (TMS)
Extracting translations for review or backup
Generating custom translation deliverables
Exporting subsets of translations using status/tag filters

Examples:

Interactive mode (prompts for options):

lingo-tracker export

Export all collections to XLIFF for all target locales:

lingo-tracker export --format xliff

Export specific collection to JSON:

lingo-tracker export --format json --collection Main

Export multiple collections for Spanish only:

lingo-tracker export --format xliff --collection Main,Admin --locale es

Export only untranslated and stale translations (default):

lingo-tracker export --format xliff --locale es
# Same as: --status new,stale

Export all translations regardless of status:

lingo-tracker export --format json --locale es --status new,translated,stale,verified

Export only verified translations:

lingo-tracker export --format xliff --status verified

Export with tag filtering:

lingo-tracker export --format json --tags ui,buttons

Export with custom filename pattern:

lingo-tracker export --format xliff --filename "translation-{source}-{target}-{date}"
# Generates: translation-en-es-2025-12-14.xliff

JSON export with hierarchical structure (default):

lingo-tracker export --format json --locale es

Output:

{
  "common": {
    "buttons": {
      "ok": "Aceptar",
      "cancel": "Cancelar"
    }
  }
}

JSON export with flat structure:

lingo-tracker export --format json --locale es --structure flat

Output:

{
  "common.buttons.ok": "Aceptar",
  "common.buttons.cancel": "Cancelar"
}

JSON export with rich objects (includes metadata):

lingo-tracker export --format json --locale es --rich --include-base --include-status

Output:

{
  "common": {
    "buttons": {
      "ok": {
        "value": "Aceptar",
        "baseValue": "OK",
        "status": "translated",
        "comment": "OK button in dialogs"
      }
    }
  }
}

Dry-run to preview export:

lingo-tracker export --format json --collection Main --locale es --dry-run

Output:

🔄 Exporting to JSON...
   Collections: Main
   Locales: es
   Output: /path/to/dist/lingo-export
   [DRY RUN]
   Processing es (42 resources)

📊 Export Summary:
   Files Created: 0
   Resources Exported: 42

Verbose output for detailed progress:

lingo-tracker export --format json --locale es --verbose

Output:

🔄 Exporting to JSON...
   Collections: Main
   Locales: es
   Output: /path/to/dist/lingo-export
   Processing es (42 resources)
   Writing /path/to/dist/lingo-export/es.json
   ✅ es: Exported 42 resources to es.json

📊 Export Summary:
   Files Created: 1
   Resources Exported: 42

📄 Summary written to: /path/to/dist/lingo-export/export-summary.md

Export Summary Report:

Every export generates an export-summary.md file in the output directory containing:

Export configuration (format, collections, locales, filters)
Statistics (resources exported, files created)
List of created files with resource counts
Warnings (overwritten files, empty results)
Errors (malformed files, missing metadata, hierarchical conflicts)

XLIFF Format Notes:

Generates XLIFF 1.2 format (industry standard)
One file per source-target locale pair
<source> contains base locale value
<target> contains translation
<note> contains translator comments (if present)
Compatible with professional translation tools (SDL Trados, MemoQ, etc.)
ICU message format preserved as-is

JSON Format Notes:

Flexible format for custom integrations
Supports both hierarchical (nested) and flat (dot-delimited) structures
Simple format (string values) ideal for direct use in applications
Rich format (object values) includes metadata for validation and processing
Collections are merged into single output (last write wins for duplicate keys)

Filtering Behavior:

Status filtering is per-locale: a resource is included in a locale if it matches the filter for that locale
Tag filtering uses OR logic: resource must have at least one of the specified tags
Base locale is never exported (only target locales)
Resources without metadata are omitted and logged in errors
Empty export results don't create files (warning logged)

Error Handling:

Malformed files: Skipped with detailed warning, export continues
Missing metadata: Resource omitted, logged in errors
Hierarchical conflicts: Logged when a key is both a parent and leaf value (JSON hierarchical only)
Non-writable output directory: Fails with clear error message
Empty results: No files created, warning shown

Notes:

Export is read-only: never modifies source translation files
Multiple collections merge into single output file per locale (last write wins)
Base locale is excluded from export (use bundle command for base locale)
Dry-run shows accurate resource counts without creating files
For detailed format specifications and examples, see Export Feature Documentation

import

Import translation resources from XLIFF or JSON files into a collection. Supports professional translation workflows, language expert verification, system migrations, and bulk corrections.

For full format specifications, workflow examples, and ICU auto-fix details, see the Import Feature Documentation.

Usage:

lingo-tracker import --source <file> --locale <locale> [options]

Options:

-f, --format <format> - Import format: xliff or json. Default: auto-detected from file extension (.xlf/.xliff → xliff; .json → json)
-s, --source <path> - Path to the import file (required)
-l, --locale <locale> - Target locale for the import, e.g., es, fr-ca (required)
-c, --collection <name> - Target collection to import into. If not specified, prompts or auto-selects
--strategy <strategy> - Import strategy (see below). Default: translation-service
--update-comments - Update resource comments from import data. Default: false
--update-tags - Update resource tags from rich JSON. Default: false
--preserve-status - Allow rich JSON to specify status (advanced). Default: false
--create-missing - Create new resources if they don't exist
--validate-base - Warn if the source base value differs from existing. Default: true
--dry-run - Preview what would be imported without modifying files. Default: false
--verbose - Show detailed import progress. Default: false

Import Strategies:

Strategy	Description
`translation-service` (default)	Sets status to `translated`. For translation agencies. Does not create missing resources.
`verification`	Sets status to `verified`. For native-speaker review and approval. Does not create missing resources.
`migration`	Sets status to `translated`. Creates missing resources (`--create-missing` defaults to `true`). Resolves Transloco-style key refs. Updates comments and tags by default.
`update`	Preserves existing status. Bulk-updates values without changing metadata. Does not create missing resources.

Examples:

Interactive mode (prompts for all required values):

lingo-tracker import

Import XLIFF from a translation service (default strategy):

lingo-tracker import \
  --source dist/lingo-import/es.xliff \
  --locale es

Import with explicit strategy:

lingo-tracker import \
  --source dist/lingo-import/fr.xliff \
  --locale fr \
  --strategy translation-service

Import for language expert verification:

lingo-tracker import \
  --source fr-reviewed.xliff \
  --locale fr \
  --strategy verification

Migrate from another translation system (creates missing resources):

lingo-tracker import \
  --source old-system-fr.json \
  --locale fr \
  --strategy migration

Bulk-correct existing translations without changing status:

lingo-tracker import \
  --source corrections-de.json \
  --locale de \
  --strategy update

Dry-run to preview what would be imported:

lingo-tracker import \
  --source translations-es.xliff \
  --locale es \
  --dry-run

Verbose output to see detailed progress:

lingo-tracker import \
  --source translations-es.xliff \
  --locale es \
  --verbose

Import into a specific collection:

lingo-tracker import \
  --source admin-es.xliff \
  --locale es \
  --collection Admin \
  --strategy translation-service

Round-Trip Workflow:

# 1. Export resources needing translation
lingo-tracker export --format xliff --locale es --status new,stale

# 2. (Send es.xliff to translation agency, receive back translated file)

# 3. Import translated file
lingo-tracker import --source es.xliff --locale es --strategy translation-service

# 4. Optionally verify with a language expert
lingo-tracker import --source es-reviewed.xliff --locale es --strategy verification

Notes:

Format is auto-detected from the file extension; use --format to override
Every import generates an import-summary.md in the import folder with statistics, status transitions, ICU auto-fixes, warnings, and errors
ICU message placeholder errors (renamed or missing placeholders) are automatically detected and fixed where possible; all auto-fixes are reported in the summary
Dry-run mode produces the same summary report using "Would" language, with no files modified
In interactive mode, a wizard guides you through source file selection, locale, collection, and strategy

AI Tooling Commands

install-skill

Generate a customised LingoTracker AI skill for use in another Angular/Transloco repository. The skill guides AI assistants (Claude Code and compatible tools) through the i18n workflow — detecting hardcoded strings, adding resources, bundling, and updating components to use Transloco.

The generated skill is pre-configured with the collection names, bundle names, and token constants of the target repository, so the AI assistant can follow the correct workflow without guessing project-specific details.

Usage:

lingo-tracker install-skill [options]

Options:

--collection <spec> - Collection specification in the format name:bundle:TokenConstant:tokenFilePath. Repeatable — pass once per collection
--dir <path> - Output directory for the skill files (default: .claude)
--token-casing <casing> - Casing style for token keys: upperCase or camelCase (default: upperCase)

Output:

Writes two files to {dir}/skills/lingo-tracker/:

SKILL.md — the main skill file, customised with the provided collection, bundle, and token values
references/patterns.md — static Angular/Transloco code pattern reference

Examples:

Interactive mode (prompts for AI tool directory, collection details, and token casing):

lingo-tracker install-skill

Interactive mode prompts:

AI tool directory: .claude (default) | .agents | .cursor
Collection details (looping — name, bundle name, token constant, token file path), with an option to add more after each
Token casing: upperCase | camelCase

Non-interactive mode with a single collection:

lingo-tracker install-skill \
  --collection trackerResources:tracker:TRACKER_TOKENS:apps/tracker/src/i18n-types/tracker-resources.ts

Non-interactive mode with multiple collections and camelCase tokens:

lingo-tracker install-skill \
  --collection trackerResources:tracker:TRACKER_TOKENS:apps/tracker/src/i18n-types/tracker-resources.ts \
  --collection adminResources:admin:ADMIN_TOKENS:apps/admin/src/i18n-types/admin-resources.ts \
  --token-casing camelCase

Output to a custom directory (e.g. for Cursor):

lingo-tracker install-skill \
  --collection myApp:main:MY_APP_TOKENS:src/i18n-types/my-app.ts \
  --dir .cursor

Collection Specification Format:

Each --collection value is a colon-separated string with four parts:

Part	Description	Example
`name`	Collection name as registered in `.lingo-tracker.json`	`trackerResources`
`bundle`	Bundle name used with `lingo-tracker bundle --name`	`tracker`
`TokenConstant`	Name of the exported TypeScript token constant	`TRACKER_TOKENS`
`tokenFilePath`	Path to the generated token file (relative to project root)	`apps/tracker/src/i18n-types/tracker-resources.ts`

Notes:

Run this command once after setting up LingoTracker in a new repository
Commit the generated skill files (.claude/skills/lingo-tracker/) to version control so the entire team benefits
If you change collection names, bundle names, or token constants, re-run the command to regenerate the skill
The --dir option should match the AI tool your team uses (.claude for Claude Code, .cursor for Cursor, etc.)

Configuration

All commands read from .lingo-tracker.json in the project root. This file is created by the init command.

Configuration Structure

{
  "exportFolder": "dist/lingo-export",
  "importFolder": "dist/lingo-import",
  "baseLocale": "en",
  "locales": ["en", "fr-ca", "es"],
  "tokenCasing": "upperCase",
  "collections": {
    "Main": {
      "translationsFolder": "apps/web/src/assets/i18n"
    },
    "Admin": {
      "translationsFolder": "apps/admin/src/assets/i18n",
      "baseLocale": "en-GB"
    },
    "DesignSystem": {
      "translationsFolder": "node_modules/@acme/design-system/i18n",
      "readOnly": true
    }
  }
}

Global fields (exportFolder, importFolder, baseLocale, locales, tokenCasing) apply to all collections and bundles by default
Per-collection fields can override global settings for specific collections
readOnly (optional, per-collection) - When true, resource mutations to this collection are blocked across the CLI, API, and UI. The collection can still be unregistered and its config entry edited. Defaults to true for node_modules paths when added via add-collection. See add-collection for details.
tokenCasing (optional) - Controls the casing style for generated type token keys. Accepts "upperCase" (default, SCREAMING_SNAKE_CASE) or "camelCase". Can be set globally or per-bundle. See Bundle Type Generation for details. Precedence: CLI flag --token-casing > per-bundle config > global config > default ("upperCase")

CI/CD Usage

All commands support non-interactive mode for use in CI/CD pipelines. To ensure non-interactive behavior:

Provide all required options via command-line flags
Use the --yes flag for commands that require confirmation (like delete-resource)
The CLI auto-detects TTY and will throw an error if required options are missing in non-interactive environments

Example CI/CD workflow:

# Initialize a project in CI
lingo-tracker init \
  --collection-name Main \
  --translations-folder src/assets/i18n \
  --base-locale en \
  --locales en fr-ca es

# Add a collection in CI
lingo-tracker add-collection \
  --collection-name Admin \
  --translations-folder src/admin/i18n

# Add a resource in CI
lingo-tracker add-resource \
  --collection Main \
  --key feature.new.title \
  --value "New Feature" \
  --comment "Title for the new feature page"

# Delete resources in CI
lingo-tracker delete-resource \
  --collection Main \
  --key "deprecated.old.feature" \
  --yes

# Validate translations before deployment (production)
lingo-tracker validate

# Validate translations with relaxed requirements (staging)
lingo-tracker validate --allow-translated

# Export translations to XLIFF for translation agency
lingo-tracker export \
  --format xliff \
  --collection Main \
  --status new,stale \
  --verbose

# Export all translations to JSON for backup
lingo-tracker export \
  --format json \
  --status new,translated,stale,verified \
  --filename "backup-{locale}-{date}"

Complete CI/CD Pipeline Example:

# GitHub Actions example
name: Build and Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '22'

      - name: Install dependencies
        run: pnpm install

      # Validate translations as quality gate
      - name: Validate translations
        run: lingo-tracker validate

      # Only build and deploy if validation passes
      - name: Build
        run: pnpm run build

      - name: Deploy
        run: pnpm run deploy

Tips and Best Practices

Key Naming Conventions

Use dot-delimited keys that reflect the hierarchy: apps.common.buttons.ok
Keys decompose into folder paths: apps.common.buttons.ok → apps/common/buttons/ folder
Keep keys descriptive and consistent across your project

Tags for Organization

Use tags to organize related resources: --tags "ui,buttons,dialogs"
Tags can be used for filtering during export/import operations
Tags are comma-separated and stored in metadata
For cross-collection tagging, use collection-level tags via edit-collection --add-tag <tag> — every resource in the collection inherits the tag without modifying individual resource_entries.json files
Collection-level tags are reflected in export --tags, bundle filtering, and the Tracker UI

Working with Multiple Collections

Use collections to separate translation sources (e.g., main app, admin panel, mobile app)
Each collection can have its own configuration overrides
Collections share global defaults unless explicitly overridden

Error Handling

Commands report errors clearly with actionable messages
Bulk operations (like delete-resource with multiple keys) use best-effort approach
Check exit codes in scripts: 0 for success, non-zero for errors

Overview​

General Usage​

Interactive vs Non-Interactive Mode​

Common Options​

Collection Commands​

init​

add-collection​

edit-collection​

delete-collection​

add-locale​

remove-locale​

Resource Commands​

add-resource​

delete-resource​

edit-resource​

translate-locale​

move​

normalize​

bundle​

Search Commands​

find-similar​

glossary​

Validation Commands​

validate​

Data Exchange Commands​

export​

import​

AI Tooling Commands​

install-skill​

Configuration​

Configuration Structure​

CI/CD Usage​

Tips and Best Practices​

Key Naming Conventions​

Tags for Organization​

Working with Multiple Collections​

Error Handling​

Overview

General Usage

Interactive vs Non-Interactive Mode

Common Options

Collection Commands

init

add-collection

edit-collection

delete-collection

add-locale

remove-locale

Resource Commands

add-resource

delete-resource

edit-resource

translate-locale

move

normalize

bundle

Search Commands

find-similar

glossary

Validation Commands

validate

Data Exchange Commands

export

import

AI Tooling Commands

install-skill

Configuration

Configuration Structure

CI/CD Usage

Tips and Best Practices

Key Naming Conventions

Tags for Organization

Working with Multiple Collections

Error Handling