Usage
# Local-only — free on every plan, no network call
vg locale config --project <slug> [--target-languages fr-FR,de-DE] [--namespaces common,checkout]
vg locale format [--dry-run]
# Cloud — needs a Vibgrate Team plan or above
vg locale push [--dry-run] [--source-only]
vg locale pull [--language <code>] [--dry-run] [--include-machine]
vg locale save-missing [--dry-run]
vg locale add <key> [value] [--namespace <ns>] [--language <code>]
vg locale remove <keys...> [--namespace <ns>]
vg locale get <key> [--namespace <ns>] [--language <code>]
vg locale status
What It Does
vg locale is the command surface for Vibgrate Localize, the managed localization product for your own applications. Your locale projects, keys, and translations live in Vibgrate Cloud and stay in sync with the locale files in your repository.
vg locale is the canonical command. vg localize is a backward-friendly alias accepting the same subcommands and flags — prefer vg locale in scripts and docs so there is one obvious form.
Local Commands Are Free; Cloud Commands Need a Team Plan
| Half | Commands | What it needs |
|---|---|---|
| Local | config, format | Nothing — filesystem only, no network call, works on every plan |
| Cloud | push, pull, save-missing, add, remove, get, status | A Vibgrate Team plan or above, and credentials |
vg locale push --dry-run sits in between: it reads your locale files and reports what a push would send without opening a connection, so you can check your path template before you have credentials.
Credentials resolve at call time — the --dsn flag, then the VIBGRATE_DSN environment variable, then your stored login.
Configuration
Settings live in vibgrate.locale.yaml at your repository root (.vibgrate/locale.yaml also works). The file never holds a credential, so it is safe to commit:
project: acme-web
sourceLanguage: en-US
targetLanguages: [fr-FR, de-DE]
format: nested
path: src/locales/{language}/{namespace}.json
namespaces: [common, checkout]
version: latest
{language} and {namespace} are substituted per file, so the template above resolves to src/locales/fr-FR/checkout.json and its siblings. Every setting has a matching flag, and flags win over the file.
Commands
| Command | Description |
|---|---|
vg locale config | Create or update vibgrate.locale.yaml |
vg locale push | Upload local locale files to Vibgrate Cloud (vg locale sync is an alias) |
vg locale pull | Write accepted translations into local files (vg locale download is an alias) |
vg locale save-missing | Create only the keys Vibgrate Cloud does not have yet — never overwrites a translation |
vg locale add | Add or update a single key |
vg locale remove | Remove one or more keys |
vg locale get | Show one key and its translations |
vg locale status | Coverage and health per language |
vg locale format | Re-format local locale files in place |
Shared Flags
Every subcommand accepts these:
| Flag | Purpose |
|---|---|
-C, --cwd <dir> | Run against this directory instead of the current one |
--dsn <dsn> | Credentials for this call (or use VIBGRATE_DSN, or sign in) |
--project <slug> | Locale project slug or id |
--format <format> | Locale file format |
--path <template> | Path template, e.g. src/locales/{language}/{namespace}.json |
--namespace <name> | Restrict to one namespace |
--language <code> | Restrict to one BCP-47 language |
--ver <version> | Target version (default: latest) |
--json | Machine-readable output |
-q, --quiet | Suppress non-essential output |
push, pull, save-missing, and format also take --dry-run, which reports what would change and writes nothing.
File Formats
Supported today: nested (the default), json (an alias for nested), flat, yaml, and yml.
The professional formats — po, xliff, xliff2, android, strings, resx, csv, arb, and properties — are recognized but not available yet. Naming one reports that it is a real format that has not shipped, rather than treating it as a typo.
Every codec round-trips, and writes are key-sorted, so pulling the same content twice produces byte-identical files instead of a spurious diff.
If a nested format cannot represent your keys — checkout.title needs checkout to be a group, while checkout alone needs it to be a value — the command names both keys and stops rather than silently dropping one. Switch that project to flat, which stores keys verbatim.
Machine Translation Is Never Silently Accepted
vg locale pull writes only translations a person has accepted. Machine output and entries awaiting review stay out of your working tree by default, because a machine draft committed into a source file is indistinguishable from reviewed copy once it lands. Pass --include-machine when you do want them.
vg locale status follows the same rule: coverage counts accepted translations, and machine and needs-review entries are listed separately.
Examples
Set up a locale project
vg locale config --project acme-web --target-languages fr-FR,de-DE --namespaces common,checkout
Preview a push before signing in
vg locale push --dry-run
Add new keys without touching existing translations
vg locale save-missing
Pull one language only
vg locale pull --language fr-FR
Read coverage as JSON in CI
vg locale status --json
Related
- Localize your app with Vibgrate Localize — the end-to-end walkthrough
- Authenticating with vg login — browser sign-in
- Create a data source with vg dsn — a token for CI, where interactive sign-in is not available
- Full command reference