Translations

The command group is translation. translations still works as an alias, so existing scripts keep running.

Push

Push a local JSON translation file to your Localess space. Only keys present in the file are affected, based on the selected update type.

localess translation push <locale> --path <file> [options]

Arguments

Argument	Description
`<locale>`	ISO 639-1 locale code (e.g., `en`, `de`, `fr`)

Options

Flag	Default	Description
`-p, --path <path>`	(required)	Path to the JSON translations file
`-f, --format <format>`	`flat`	File format: `flat` or `nested`
`-t, --type <type>`	`add-missing`	Update strategy: `add-missing`, `update-existing`, or `delete-missing`
`--dry-run`	`false`	Preview changes without applying them
`-a, --all`	`false`	Also print unchanged keys in the preview
`-y, --yes`	`false`	Skip the confirmation prompt for `update-existing` and `delete-missing`
`-v, --verbose`	`false`	Print verbose debug output

Push previews the change before applying it, using the same grouped report as diff. The destructive strategies (update-existing, delete-missing) confirm before writing unless you pass -y.

Update Strategies

Type	Description
`add-missing`	Adds translations for keys that do not yet exist in Localess
`update-existing`	Updates translations for keys that already exist in Localess
`delete-missing`	Deletes translations in Localess for keys that are absent from the local file

File Formats

flat — A flat JSON object where keys may use dot notation:

{
  "common.submit": "Submit",
  "nav.home": "Home"
}

nested — A nested JSON object that is automatically flattened before uploading:

{
  "common": { "submit": "Submit" },
  "nav": { "home": "Home" }
}

Examples

# Push English translations (add missing keys only)
localess translation push en --path ./locales/en.json

# Push with update-existing strategy
localess translation push en --path ./locales/en.json --type update-existing

# Delete keys in Localess absent from the local file
localess translation push en --path ./locales/en.json --type delete-missing

# Preview changes without applying (dry run)
localess translation push en --path ./locales/en.json --dry-run

# Push nested-format translations
localess translation push de --path ./locales/de.json --format nested

Pull

Pull translations from your Localess space and save them to a local file.

localess translation pull <locale> --path <file> [options]

Arguments

Argument	Description
`<locale>`	ISO 639-1 locale code (e.g., `en`, `de`, `fr`)

Options

Flag	Default	Description
`-p, --path <path>`	(required)	Output file path
`-f, --format <format>`	`flat`	File format: `flat` or `nested`
`--draft`	`false`	Pull the draft (unpublished) version of translations
`-v, --verbose`	`false`	Print verbose debug output

Examples

# Pull English translations as flat JSON
localess translation pull en --path ./locales/en.json

# Pull German translations as nested JSON
localess translation pull de --path ./locales/de.json --format nested

# Pull draft (unpublished) translations
localess translation pull en --path ./locales/en.json --draft

Compare a local translations file against your space without changing either side. Use it as a CI gate — the command exits 1 when anything differs, so a pipeline step fails if translations have drifted out of sync.

localess translation diff <locale> --path <file> [options]

Arguments

Argument	Description
`<locale>`	ISO 639-1 locale code (e.g., `en`, `de`, `fr`)

Options

Flag	Default	Description
`-p, --path <path>`	(required)	Path to the local translations file
`-f, --format <format>`	`flat`	File format: `flat` or `nested`
`--draft`	`false`	Compare against the draft version
`-a, --all`	`false`	Also print unchanged keys
`-v, --verbose`	`false`	Print verbose debug output

Report format

Keys are grouped by what would happen to them, in a git-diff style:

Section	Symbol	Meaning
`Create`	`+`	In the local file, missing from the space
`Update`	`~`	In both, with a different value
`Stale`	`-`	In the space, missing from the local file

Empty sections are omitted. Unchanged keys collapse into an N unchanged (use --all to show) line, so a normal run stays readable. The report ends with either a summary count or In sync.

Examples

# Check for drift
localess translation diff en --path ./locales/en.json

# Include unchanged keys in the report
localess translation diff en --path ./locales/en.json --all

Push

Arguments

Options

Update Strategies

File Formats

Examples

Pull

Arguments

Options

Examples

Diff

Arguments

Options

Report format

Examples

On this page