title	Import
sidebar_position	3

Import Feature

The Import feature allows you to import translation resources from external sources in standard formats (XLIFF and JSON), supporting professional translation workflows, system migrations, and expert verification processes.

Usage

lingo-tracker import -s <file> -l <locale> [options]
# or
lingo-tracker import --source <file> --locale <locale> [options]

Formats

LingoTracker automatically detects the import format from the file extension:

.xliff, .xlf: XLIFF 1.2 format (industry standard for professional translation services)
.json: JSON format (flexible for migrations and integrations)

You can explicitly specify the format with --format <format> if needed.

Options

Option	Description	Default
`-s, --source <file>`	Path to import file (required).	-
`-l, --locale <locale>`	Target locale for import (e.g., `es`, `fr-ca`).	-
`-f, --format <format>`	Import format (`xliff` or `json`).	Auto-detect from extension
`-c, --collection <name>`	Target collection to import into.	Default collection
`--strategy <strategy>`	Import strategy (see below).	`translation-service`
`--update-comments`	Update resource comments from import data.	`false`
`--update-tags`	Update resource tags from rich JSON.	`false`
`--preserve-status`	Allow rich JSON to specify status (advanced).	`false`
`--create-missing`	Create new resources if they don't exist.	Strategy-dependent
`--validate-base`	Warn if source base value differs from existing.	`true`
`--dry-run`	Preview import without modifying files.	`false`
`--verbose`	Show detailed import progress.	`false`

Note: Files larger than 5 MB will show a warning before import begins.

Import Strategies

Different import workflows require different approaches. The --strategy option selects the appropriate behavior:

translation-service (Default)

Use Case: Importing translations from professional translation houses/services

Behavior:

Sets status to translated for all imported values
Preserves existing base values (warns if source differs)
Does NOT create new resources (skips missing resources; counted in Resources Skipped, not an error)
Does NOT update comments or tags by default
Collection-level inherited tags are not stored in bundle files — they re-apply automatically based on the destination collection's own config after import

Typical Workflow:

Export resources with status new,stale to XLIFF
Send to translation service
Receive translated XLIFF files back
Import with strategy translation-service

Example:

lingo-tracker import --source translations-es.xliff --locale es --strategy translation-service

verification

Use Case: Language experts verifying and approving translations

Behavior:

If imported value matches existing value: sets status to verified (approval without changes)
If imported value differs: updates value and sets status to verified (approved with corrections)
Does NOT create new resources
Preserves existing base values

Example:

lingo-tracker import --source verified-fr.xliff --locale fr --strategy verification

migration

Use Case: Migrating from another translation system (Transloco, i18next, etc.)

Behavior:

Creates new resources with base values from XLIFF <source> or JSON baseValue
Sets status to translated (use --preserve-status with rich JSON to honor source status)
Resolves Transloco key references (e.g., {{t('other.key')}}, {{key}}) by inlining the referenced value; missing references emit a "Missing reference target" warning and circular references emit a "Circular reference detected" warning — both are preserved as literals
Normalizes Transloco plural/select syntax to ICU format
Overwrites existing values and metadata

Flags Default:

--create-missing: true (applied automatically for migration strategy)
--update-comments: false (pass explicitly to enable)
--update-tags: false (pass explicitly to enable)

Example:

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

update

Use Case: Bulk updates to existing translations (maintaining existing status)

Behavior:

Updates only existing resources (skips missing resources; counted in Resources Skipped, not an error)
Preserves existing status (does NOT change to translated)
Does NOT create new resources
Useful for fixing typos or updating specific translations

Example:

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

Import Formats

XLIFF 1.2

XLIFF (XML Localization Interchange File Format) is the industry standard for professional translation services.

Format Specification:

<trans-unit> IDs are interpreted as full dot-delimited keys (e.g., common.buttons.cancel)
<source> contains base locale value (used for validation/creation)
<target> contains translation to import
<note> contains comment (optional). A trans-unit with several notes gets one comment, one note per line. LingoTracker ignores a note that starts with Do not translate:, because export adds that note to list the protected terms. It is not part of the comment.

Example:

<xliff version="1.2">
  <file source-language="en" target-language="es">
    <body>
      <trans-unit id="common.buttons.cancel">
        <source>Cancel</source>
        <target>Cancelar</target>
        <note>Button text for canceling actions</note>
      </trans-unit>
    </body>
  </file>
</xliff>

JSON

JSON import provides flexible format options for system migrations and integrations.

Structure Options:

Flat: Dot-delimited keys at root level
Hierarchical: Nested objects (auto-detected)

Value Format Options:

Simple: String values only
Rich: Objects with metadata (value, comment, baseValue, status, tags)

Flat with Simple Values:

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

Hierarchical with Simple Values:

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

Flat with Rich Objects:

{
  "common.buttons.cancel": {
    "value": "Cancelar",
    "comment": "Button text for canceling actions",
    "baseValue": "Cancel",
    "status": "verified",
    "tags": ["ui", "common"]
  }
}

Protected Term Verification

LingoTracker checks every incoming translation against the protected terms for its collection. Those terms come from two files. LingoTracker combines the global file with the collection's own file.

A term may appear in the stored source value and be missing from the incoming translation. That entry then fails:

❌ "app.checkout.title" Protected term(s) altered: iPhone

LingoTracker skips the entry and reports it as failed. The rest of the import continues normally.

LingoTracker matches the source case-insensitively. It requires the translation to hold the term exactly as stored. That difference is deliberate, and it is what catches iPhone coming back as iphone or as Iphone.

Base-locale imports skip the check, because a base-locale import defines the source rather than translating it. An import in a project with no protected terms also skips it.

Preferred Terminology Warnings

A base-locale import (--strategy migration into the base locale) checks every value it writes against the preferred terminology rules (.lingo-tracker-preferred-terminology.json, or the file named by preferredTerminologyFile). Each discouraged term found adds one warning, whichever way it is capitalized and however often it occurs in the value:

Preferred terminology: key "budget.title" — consider "Investment" instead of "Expenditure". Finance style guide

The warnings are advisory. The value is imported as-is, nothing is skipped or failed, and the exit code is unchanged. A dry run reports the same warnings.

Target-locale imports are never checked. Translations use their own vocabulary.
A broken rule file (invalid JSON or invalid rules) adds one warning, Preferred terminology checks skipped: …, and the import continues without the check.
A missing file at the default path means no rules. A missing file named explicitly by preferredTerminologyFile adds one warning.

The Preferred Terminology page explains the rules and how matching works.

ICU Format Auto-Fixing

LingoTracker automatically fixes common ICU message format placeholder errors made by translators:

What Gets Auto-Fixed:

Renamed placeholders: {nombre} → {name}
Missing placeholders: Inserts single missing placeholder
Plural/select form corrections: {numero, plural, ...} → {count, plural, ...}

What Gets Reported:

All auto-fixes are logged in the import summary with before/after values
Errors for unfixable cases (multiple missing placeholders, malformed syntax) — the resource import fails and is counted in Resources Failed

Example:

Original: "Hola {nombre}, tienes {numero} mensajes"
Auto-Fixed: "Hola {name}, tienes {count} mensajes"

This ensures translations work correctly even when translators accidentally modify placeholder names.

Import Summary

Every completed import writes a timestamped lingo-tracker-import-summary-<timestamp>.md file to 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 detailed change tracking:

Import statistics (resources imported, created, updated, skipped, failed)
Status transitions (e.g., "new → translated", "stale → verified")
ICU auto-fixes applied
Files modified
Warnings and errors
Detailed change log (first 20 resources)

Exit code: The command exits with code 1 when any resources fail or errors occur. Skipped resources (missing from storage) do not cause a non-zero exit, so CI pipelines will not fail on skips alone.

Dry-Run Mode

Use --dry-run to preview what would be imported without modifying files:

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

The dry-run summary shows exactly what would happen, using "Would" language to indicate no changes were made. The summary file is not written in dry-run mode, but the temp path where it would be written is still printed to the console.

Interactive Mode

If you run lingo-tracker import without required options in a terminal, it will launch an interactive wizard to guide you through:

Source file path entry (with path validation)
Format auto-detection
Target locale selection (from configured locales)
Collection selection (if multiple exist)
Import strategy selection with descriptions
Strategy-specific options

Round-Trip Workflow

LingoTracker supports professional translation workflows:

Export for Translation:

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

Send to Translation Service:
- Upload es.xliff to professional translation service
- Translators work on translations

Import Translated Files:

lingo-tracker import --source es.xliff --locale es --strategy translation-service

Review Import Summary:
- Check the summary file (path printed to console) for statistics and warnings
- Review any ICU auto-fixes applied
- Verify all translations imported successfully
Verification (Optional):
- Export again for language expert review
- Import with --strategy verification to mark as verified

Examples

Professional Translation Service

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

# After receiving translated files back
lingo-tracker import --source es.xliff --locale es --strategy translation-service
lingo-tracker import --source fr.xliff --locale fr --strategy translation-service
lingo-tracker import --source de.xliff --locale de --strategy translation-service

Language Expert Verification

# Export all translations for review
lingo-tracker export --format xliff --locale es

# After expert review
lingo-tracker import --source es-reviewed.xliff --locale es --strategy verification

Bulk Corrections

# Export current translations
lingo-tracker export --format json --locale es

# Edit JSON file to fix typos
# Import corrections
lingo-tracker import --source es-corrected.json --locale es --strategy update

Migrating from Another System

See the Migration Guide for detailed instructions on migrating from Transloco, i18next, and other translation systems.

FilesExpand file tree

import.md

Latest commit

History

import.md

File metadata and controls

Import Feature

Usage

Formats

Options

Import Strategies

translation-service (Default)

verification

migration

update

Import Formats

XLIFF 1.2

JSON

Protected Term Verification

Preferred Terminology Warnings

ICU Format Auto-Fixing

Import Summary

Dry-Run Mode

Interactive Mode

Round-Trip Workflow

Examples

Professional Translation Service

Language Expert Verification

Bulk Corrections

Migrating from Another System