Translations

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

PushCopy Anchor Link

Push a local JSON translation file to your Localess space. The update type decides which keys are affected: add-missing and update-existing act on keys in the file, while the two delete types act on keys missing from it.

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

ArgumentsCopy Anchor Link

OptionsCopy Anchor Link

For update-existing and the two delete types, push first asks the server for a dry run and lists the keys it would change — + in green, ~ in yellow, - in red. It then asks for confirmation, defaulting to No; declining prints Aborted. and exits 1. Pass -y to skip the prompt, or --dry-run to print the list without writing anything. update-existing lists only keys whose value actually differs.

add-missing doesn't ask: it writes immediately, then lists the keys it added.

update-existing also prints a notice before it runs. A file from a plain translation pull holds the fallback locale's text for keys with no value in this locale, and pushing it back would save that text as translations. Pull with --raw for files you edit and push back.

Update StrategiesCopy Anchor Link

The former delete-missing type was split into delete-missing-key and delete-missing-value, and is no longer accepted. Update scripts that still pass it, and update your Localess deployment together with the CLI — an older deployment rejects the new types.

File FormatsCopy Anchor Link

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

  Copy Text

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

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

  Copy Text

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

ExamplesCopy Anchor Link

# 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 absent from the source-locale file, in every locale
localess translation push en --path ./locales/en.json --type delete-missing-key

# Remove only the German values of keys absent from the German file
localess translation push de --path ./locales/de.json --type delete-missing-value

# 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

PullCopy Anchor Link

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

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

ArgumentsCopy Anchor Link

OptionsCopy Anchor Link

By default, pull reads the published translations — or the draft ones with --draft — the same way your app does: keys with no value in this locale are filled from the fallback locale. That's what you want for a file your app loads at runtime. --raw instead reads only the values stored for this locale and leaves the gaps out. It already reads the current, unpublished values, so it can't be combined with --draft. --raw needs a recent platform: update your Localess deployment together with the CLI.

If the locale isn't in the space, pull exits 1 with Locale '<locale>' is not in this space. Available locales: …. This check reads the space, so it's skipped silently when your token lacks the Development Tools permission.

With --format nested, a key that is also the parent of other keys — button beside button.save — can't hold a value, so its value is left out. Pull warns, names the dropped keys, and suggests --format flat to keep them.

Round-tripping a fileCopy Anchor Link

To edit translations locally and push them back, pull with --raw so the file holds only this locale's own values, then push with update-existing:

localess translation pull de --path ./locales/de.json --raw
# edit ./locales/de.json
localess translation push de --path ./locales/de.json --type update-existing

A file pulled without --raw would push the fallback locale's text back as German translations.

ExamplesCopy Anchor Link

# 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

# Pull only the stored German values, for editing
localess translation pull de --path ./locales/de.json --raw

DiffCopy Anchor Link

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]

ArgumentsCopy Anchor Link

OptionsCopy Anchor Link

Diff compares against the published translations by default. --raw can't be combined with --draft, and the unknown-locale check works as it does for pull.

Report formatCopy Anchor Link

Keys are grouped in a git-diff style. The labels are direction-neutral, since the same difference means "push would add it" or "pull would remove it":

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 line such as 5 translation(s) differ: 2 only in file, 1 different, 2 only in Localess. or In sync.

ExamplesCopy Anchor Link

# 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