Troubleshooting

Authentication

"Not logged in"

Most commands require authentication. Log in first:

localekit login --email you@example.com

Check your current session:

localekit whoami

"Solo plan required"

The translate and sync commands require a Solo subscription or higher. Check your tier:

localekit whoami --json

Translation

"API key required"

Cloud engines (DeepL, OpenAI) need an API key. Set it via:

Environment variable

export DEEPL_API_KEY="your-key"

CLI flag

localekit translate --api-key your-key

Config file

deeplApiKey: ${DEEPL_API_KEY}

The CLI checks in this order: --api-key flag → LOCALEKIT_API_KEY env → engine-specific env (DEEPL_API_KEY / OPENAI_API_KEY) → config file.

"No localization files found"

LocaleKit could not detect any supported localization files. Verify:

1. You're in the right directory (or pass --config / a path)
2. Your project has localization files in a supported format
3. Run localekit scan --detailed to see what's detected

MLX model download hangs

MLX models download from Hugging Face on first use. If it stalls:

1. Check your internet connection
2. Clear the cache: rm -rf ~/Library/Caches/huggingface/
3. Try a smaller model: --mlx-model mlx-community/Qwen3-4B-4bit

GitHub Sync

"Token missing" or 403 error

The sync command needs a GitHub token with Contents (read/write) and Pull requests (read/write) permissions. See the sync command for setup instructions.

"No GitHub config"

The CLI couldn't determine the repository. Specify it via:

localekit sync --repo owner/repo

Or add to .localekitrc.yml:

github:
  repo: owner/repo

The CLI also infers the repo from your git remote origin URL.

Validation

Warnings vs errors

By default, localekit validate exits 0 for warnings and 1 for errors. Use --strict to fail on warnings too:

localekit validate --strict

Diff

"No snapshot found"

localekit diff requires a .localekit-snapshot.json file created by a previous localekit translate run. Run translate first to create the baseline.