Overview
vg locale is the command surface for Vibgrate Localize: managed localization for your application. Your locale projects, keys, and translations live in Vibgrate Cloud and stay in sync with the locale files in your repository.
The loop is three commands. Point the repo at a project, push your source keys up, pull accepted translations back down:
vg locale config --project acme-web --target-languages fr-FR,de-DE
vg locale push
vg locale pull
vg locale is the canonical command. vg localize is a backward-friendly alias that accepts exactly 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
The command set splits in two, and the split is deliberate:
| Half | Commands | What it needs |
|---|---|---|
| Local | config, format | Nothing. They only touch the filesystem, make no network call, and work on every plan — including Vibgrate Free |
| Cloud | push, pull, save-missing, add, remove, get, status | A Vibgrate Team plan or above, and credentials |
vg locale push --dry-run is the useful middle case: 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, in this order: the --dsn flag, then the VIBGRATE_DSN environment variable, then your stored login — exactly as vg push does. Run vg login for interactive use, or create a token with vg dsn for CI.
Configuration
Settings live in vibgrate.locale.yaml at the root of your repository (.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
The path template tells Vibgrate Localize where your locale files are. {language} and {namespace} are substituted per file, so the example above resolves to src/locales/fr-FR/checkout.json and its siblings.
Every setting has a matching flag (--project, --format, --path, --namespace, --language, --ver), and flags win over the file — handy for a one-off run against a single language without editing the config.
File formats
Five formats are supported today:
| Format | Written as | Notes |
|---|---|---|
nested | Nested JSON | The default. Dotted keys expand into groups |
json | Nested JSON | Alias for nested |
flat | Flat JSON | Keys stored verbatim, dots and all |
yaml / yml | YAML | Same nesting rules as nested |
The professional formats — po, xliff, xliff2, android, strings, resx, csv, arb, and properties — are recognized but not available yet. Naming one tells you it is a real format that has not shipped, rather than reporting it as a typo.
Two properties make these safe to run over a working tree. Every codec round-trips, so decoding and re-encoding a file returns what you started with. And writes are key-sorted, so pulling the same content twice produces byte-identical files instead of a diff that trains your team to stop reading them.
If a nested format cannot represent your keys — checkout.title needs checkout to be a group, while checkout on its own 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 still waiting for review stay out of your working tree by default, because a machine draft committed into a source file is indistinguishable from reviewed copy the moment it lands.
Pass --include-machine when you do want them — for a preview branch, or a language where a rough draft beats an empty string.
The same rule holds in reporting: vg locale status counts accepted translations toward coverage and lists machine and needs-review entries separately.
Command reference
| Command | Description |
|---|---|
vg locale config | Create or update vibgrate.locale.yaml (no credentials are stored in it) |
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 |
Flags every subcommand accepts
| 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.
Where the dashboard fits
The same locale projects appear in Vibgrate Cloud under Estate ▸ Localize, where you can browse keys, filter by translation status, edit translations inline, and read per-language coverage. The CLI and the dashboard are two views of one project: push from your repo, translate in the browser, pull the result back.
Related
- vg login — browser sign-in, the usual way to get credentials
- vg dsn — create a token for CI, where interactive sign-in is not available
- Command reference — every
vgsubcommand in one inventory