CLI Reference

Usage

Run the CLI using npx. No installation required.

npx @localheroai/cli <command>

New here? Jump to Common workflows for copy-paste examples of the everyday tasks.

View on npm · View on GitHub

Commands

init

Set up your project configuration. Creates localhero.json and optionally sets up GitHub Actions.

npx @localheroai/cli init

See Project Setup for a detailed walkthrough.

login

Authenticate with your API key. Saves to .localhero_key and adds it to .gitignore.

npx @localheroai/cli login

Usually not needed since init handles authentication.

translate

Generate translations for keys missing translations. Updates your local translation files with the results.

npx @localheroai/cli translate

--verbose Show detailed output

--commit Automatically commit changes

--changed-only Only translate keys changed in current branch

push

Upload translation files to Localhero.ai. Syncs your local keys and translations to the dashboard.

npx @localheroai/cli push

--verbose Show detailed output

--yes Skip confirmation prompt

--force Push all files, not just changes

--prune Delete keys that no longer exist in local files

pull

Download translations from Localhero.ai to your local files. Use after editing translations in the dashboard.

npx @localheroai/cli pull

--verbose Show detailed output

--changed-only Only pull keys changed in current branch

clone

Download all translation files from Localhero.ai. Useful for build pipelines where translation files aren't in version control.

npx @localheroai/cli clone

--verbose Show detailed output

--force Overwrite existing files

ci

Optimized command for CI/CD environments. Automatically detects context and runs appropriate operations.

npx @localheroai/cli ci

See GitHub Actions for setup details.

--verbose Show detailed output

Common workflows

A few everyday tasks and the commands that handle them.

Sync your local keys to the dashboard

Push the keys and translations from your local files.

npx @localheroai/cli push

Remove keys you renamed or deleted

push only adds and updates, it never deletes. To also remove keys that no longer exist locally (e.g. after renaming or moving sections), add --prune. Pair it with --force so unchanged files are checked too. It lists the keys it would remove and asks before deleting.

npx @localheroai/cli push --prune --force

Get dashboard edits back into your files

Pull translations edited in Localhero.ai down to your local files.

npx @localheroai/cli pull

Fill in missing translations

Generate translations for any keys missing them and write the results back to your files.

npx @localheroai/cli translate

Stop syncing certain keys

Add a glob to ignoreKeys in localhero.json. This filters them from future syncs, it does not remove keys already on the dashboard, use --prune for that.

"translationFiles": { "ignoreKeys": ["system.*"] }

Configuration File

The localhero.json file contains your project configuration. Created automatically by the init command.

Example · localhero.json

{
  "schemaVersion": "1.0",
  "projectId": "prj_abc123",
  "sourceLocale": "en",
  "outputLocales": ["fr", "de", "es"],
  "translationFiles": {
    "paths": ["config/locales/"],
    "pattern": "**/*.{json,yml,yaml}",
    "ignore": ["**/test/**"]
  }
}

projectId Your unique project identifier from Localhero.ai

sourceLocale The language you write your app in (must match filename exactly)

outputLocales Array of target languages (must match filenames exactly)

translationFiles.paths Directories containing translation files

translationFiles.pattern Glob pattern for file matching

translationFiles.ignore Patterns to exclude from translation

translationFiles.multiLanguageFiles beta Detect files with all locales as top-level keys (YAML/JSON only)

customLocales beta Declare non-standard locale codes (e.g. ja_easy) so they're accepted as target languages

The --changed-only flag compares against the main branch by default.

Locale codes must match your filenames exactly

config/locales/en.yml → "sourceLocale": "en"

locales/en-US/common.json → "sourceLocale": "en-US"

locale/pt_BR.po → "outputLocales": ["pt_BR"]

beta Multi-language files

If your project has files where all locales live in one file with top-level locale keys (common in Rails apps with view-level i18n), enable detection by adding multiLanguageFiles: true to translationFiles.

For example if you have files like this:

en:
  subject: "Welcome"
sv:
  subject: "Välkommen"
nb:
  subject: "Velkommen"

Detection rule: every top-level key in the file must be a configured locale (sourceLocale or outputLocales), and there must be at least two. Supported formats: YAML, JSON. Not PO.

beta Custom locales

If your app uses a non-standard locale code that isn't a recognised language (e.g. ja_easy for simplified Japanese), declare it under customLocales so Localhero.ai accepts it as a target language.

"customLocales": [
  { "code": "ja_easy", "name": "Easy Japanese", "baseLanguage": "ja" }
],
"outputLocales": ["fr", "de", "ja_easy"]

Custom locales are registered with Localhero.ai when init sets up the project, so declare them during setup. Adding one to localhero.json afterward and running push won't register it currently.

Each entry needs a code (matching your filenames), a human-readable name, and a baseLanguage (an ISO-639-1 code that drives plural rules and the flag). Every custom code must also appear in outputLocales.

Environment Variables

For CI/CD environments where the .localhero_key file isn't available.

LOCALHERO_API_KEY

Your API authentication key. Takes precedence over .localhero_key file.

export LOCALHERO_API_KEY="your-key-here"

Usage

Commands

Common workflows

Configuration File

Environment Variables

Redo att testa?