Export Feature

The Export feature allows you to export translation resources from LingoTracker into standard formats (XLIFF and JSON) for integration with translation services and external systems.

Usage

lingo-tracker export --format <format> [options]

Formats

• xliff: XLIFF 1.2 format (standard for translation tools).
• json: JSON format (flexible for developer workflows).

Options

Option	Description	Default
-f, --format <format>	Export format (xliff or json).	Required (or interactive)
-c, --collection <names>	Comma-separated list of collections to export.	All collections
-l, --locale <locales>	Comma-separated list of target locales. The base locale is always excluded.	All target locales
-s, --status <statuses>	Filter by status (new, translated, stale, verified).	new,stale
-t, --tags <tags>	Filter by tags (comma-separated). Matches against the resource's effective tags — the union of per-resource tags and the collection's inherited tags.	None
-o, --output <path>	Output directory. Defaults to exportFolder from config if set.	dist/lingo-export
--filename <pattern>	Custom filename pattern. The extension (.xliff or .json) is appended automatically if omitted.	<locale>.xliff or <locale>.json
--no-protect-notes	Leave protected-term annotations off exported entries.	Annotations on
--dry-run	Preview export without writing files.	false
--verbose	Show detailed progress.	false

JSON Specific Options

Option	Description	Default
--structure <type>	hierarchical or flat.	hierarchical
--rich	Output rich objects with metadata instead of plain string values.	false
--include-base	Include base locale value in the output object.	false
--include-status	Include translation status in the output object.	false
--include-comment	Include comments in the output object.	false
--include-tags	Include tags array in the output object.	false
--base-property-name <name>	Property name for the base locale value in JSON output. Only applies with --include-base. Reserved names (value, comment, status, tags) are rejected.	baseValue

Filename Placeholders

You can use the following placeholders in --filename. If no file extension is included, the correct extension for the format (.xliff or .json) is appended automatically.

• {locale} / {target}: The target locale code (e.g., es, fr-ca). These are interchangeable.
• {source}: The base locale code (e.g., en).
• {date}: Current date (YYYY-MM-DD).

Example:

lingo-tracker export --format json --filename "translations-{source}-to-{target}-{date}"
# Generates: translations-en-to-es-2025-12-13.json

Examples

Export all untranslated and stale strings to XLIFF for all target locales:

lingo-tracker export --format xliff

Export only Spanish strings with new or stale status from a specific collection:

lingo-tracker export --format xliff --locale es --collection marketing --status new,stale

Export all target locales to flat JSON with a custom filename:

lingo-tracker export --format json --structure flat --filename "{locale}-translations"
# Generates: es-translations.json, fr-translations.json, etc.

Export JSON with comments only (any --include-* flag automatically produces rich objects):

lingo-tracker export --format json --include-comment

Export rich JSON including base values and comments (useful for translator context):

lingo-tracker export --format json --include-base --include-comment

Export rich JSON with a custom property name for the base value (e.g. for tools that expect original instead of baseValue):

lingo-tracker export --format json --rich --include-base --base-property-name original

Preview an export without writing any files:

lingo-tracker export --format xliff --dry-run

Customising the Base Value Property Name

When exporting to JSON with --include-base, the base locale value is added to each object under the key baseValue by default. Use --base-property-name to override this when integrating with translation management systems or external tools that expect a different property name:

# Produce: { "value": "Aceptar", "original": "OK" }
lingo-tracker export --format json --include-base --base-property-name original

# Produce rich objects: { "value": "Aceptar", "source": "OK", "comment": "OK button" }
lingo-tracker export --format json --include-base --include-comment --base-property-name source

The names value, comment, status, and tags are reserved — they are existing fields in rich JSON objects and cannot be used as the base property name. Using a reserved name exits with an error before any files are written.

Protected Term Annotations

Export marks the protected terms it finds in each entry's source value. Translators and machine-translation services then know which words to leave unchanged.

In rich JSON, the terms appear under doNotTranslate:

{
  "app.checkout.title": {
    "value": "Comprar con iPhone",
    "doNotTranslate": ["iPhone"]
  }
}

In XLIFF, they become a note on the trans-unit:

<note>Do not translate: iPhone</note>

The terms that apply come from two files. LingoTracker combines the global protected-terms file with the exported collection's own file.

Matching is case-insensitive and matches whole words only. LingoTracker therefore marks iPhone in Buy an IPHONE, and leaves it unmarked in iPhones.

Base-locale rows stay unmarked, because a base-locale row holds nothing to translate. To turn off marking entirely, pass --no-protect-notes.

XLIFF Source and Target Language

XLIFF 1.2 exports now include the source-language and target-language attributes on the <file> element, matching the XLIFF 1.2 spec. This improves compatibility with translation tools that parse these attributes to determine locale mapping:

<file original="translations" source-language="en" target-language="es" datatype="plaintext">

Export Summary

Every export generates a timestamped lingo-tracker-export-summary-<timestamp>.md file in the OS temp directory (e.g. /tmp on macOS/Linux, %TEMP% on Windows) and prints the full path to the console. The file is written outside your project tree to avoid polluting your repository or breaking build pipelines that scan .md files. It contains:

• Metadata: date, format, collections, target locales, status and tag filters applied.
• Results: resources exported, files created, output directory.
• File list: each file generated (or that would be generated in a dry run).
• Warnings: e.g., files that were overwritten.
• Errors: broken down into general errors, malformed files, resources omitted due to missing metadata, and hierarchical key conflicts (JSON only — when a key like a.b.c conflicts with a parent key a.b).

In a dry run, the summary is printed to the console instead of written to disk. Note: even in dry-run mode, the output directory is created on disk if it does not already exist.

Interactive Mode

If you run lingo-tracker export without the --format flag in a TTY terminal, an interactive wizard guides you through all options. In non-interactive environments (CI, pipes), --format is required and omitting it is an error. All other unspecified options fall back silently to their documented defaults — pass all relevant flags explicitly in scripts rather than relying on interactive prompts.