localekit sync

Translate and push localization files to GitHub as a pull request

Solo plan

GitHub Token

The sync command needs a GitHub personal access token to create pull requests.

Create a token

1. Go to github.com/settings/tokens → Generate new token (Fine-grained)
2. Set a name (e.g., localekit) and expiration
3. Under Repository access, select the target repository
4. Under Permissions → Repository permissions, grant:

Permission	Access	Why
Contents	Read and write	Push translated files
Pull requests	Read and write	Create and update PRs
Metadata	Read-only	Required by GitHub

5. Click Generate token and copy it

Set the token

export GITHUB_TOKEN="ghp_your_token_here"

Or pass it directly:

localekit sync --github-token ghp_your_token_here

Or add to .localekitrc.yml:

github:
  token: ${GITHUB_TOKEN}
  repo: owner/repo
  baseBranch: main

Quick Start

DeepL

localekit sync --engine deepl --api-key $DEEPL_API_KEY

OpenAI

localekit sync --engine openai --api-key $OPENAI_API_KEY

MLX

localekit sync --engine mlx --mlx-model mlx-community/Qwen3-4B-4bit

See Translation Engines for a detailed comparison and available MLX models.

Usage

localekit sync [path] [options]

Arguments

Argument	Description	Default
path	Path to localization file or directory (defaults to current directory)	.

Options

Option	Description	Default
--config <config>	Path to configuration file (.localekitrc.yml)	—
-l, --languages <languages>	Target languages to translate (comma-separated, e.g., 'de-DE,fr-FR')	—
--engine <engine>	Translation engine: openai, deepl, mlx	deepl
--api-key <api-key>	API key (or use LOCALEKIT_API_KEY, DEEPL_API_KEY, or OPENAI_API_KEY env var)	—
--github-token <github-token>	GitHub personal access token (or use GITHUB_TOKEN env var)	—
--repo <repo>	GitHub repository in owner/repo format	—
--branch <branch>	Branch name for the PR (default: localekit/translations-YYYY-MM-dd)	—
--base <base>	Base branch to target the PR against	main
--title <title>	Pull request title	Update translations via LocaleKit
--message <message>	Commit message	Update translations
--source-language <source-language>	Base/source language (e.g., en-US)	—
--mlx-model <mlx-model>	MLX model ID from Hugging Face (e.g., mlx-community/Qwen3-4B-4bit)	—

Flags

Flag	Description
--skip-translate	Skip translation and only push existing files
--dry-run	Preview changes without pushing to GitHub
-v, --verbose	Show detailed output

MLX (on-device)

6 models available — from Qwen3 4B (8 GB RAM) to Qwen3 32B (32 GB RAM). See all models and comparison.