Localize your app with Vibgrate Localize

What You Will Do

Take an application that already has locale files in its repository, connect it to Vibgrate Localize, get translations done, and pull the results back into your codebase. Roughly ten minutes of work, most of it waiting for translations.

Vibgrate Localize localizes your application. A locale project holds your keys and their translations; the CLI keeps that project and the locale files in your repo in sync.

Before You Start

• The Vibgrate CLI installed, and a repository with locale files in it
• For the cloud steps, a Vibgrate Team plan or above. Steps 1 and 5 are local-only and work on every plan

If you do not have the CLI yet:

npx @vibgrate/cli scan

Step 1 — Point Your Repo at a Locale Project

Run this at the root of your repository:

vg locale config --project acme-web --target-languages fr-FR,de-DE --namespaces common,checkout

That writes vibgrate.locale.yaml:

project: acme-web
sourceLanguage: en-US
targetLanguages: [fr-FR, de-DE]
format: nested
path: src/locales/{language}/{namespace}.json
namespaces: [common, checkout]
version: latest

Commit this file. It never holds a credential — your DSN resolves at call time from --dsn, VIBGRATE_DSN, or your stored login.

The one setting worth checking is path. {language} and {namespace} are substituted per file, so the template above looks for src/locales/en-US/common.json, src/locales/fr-FR/checkout.json, and so on. If your layout differs — say one file per language with no namespaces — set it now:

vg locale config --path "locales/{language}.json" --namespaces common

Step 2 — Check What Would Be Sent

Before you send anything, confirm the CLI actually finds your files:

vg locale push --dry-run

A dry run makes no network call and needs no credentials, so this works before you have signed in. It reports the number of keys and the files they came from. If it reports zero keys, your path template does not match your layout — fix it and run the dry run again.

Step 3 — Push Your Source Keys

Sign in, then push:

vg login
vg locale push

Every key in your source-language files is created in Vibgrate Cloud, along with any translations you already have. The output tells you how many keys were created, how many were updated, and how many translations were written.

For day-to-day use afterward, prefer the safer verb:

vg locale save-missing

save-missing sends only keys Vibgrate Cloud does not have yet. It never overwrites a translation, which makes it the right command to wire into a pre-commit hook or a CI job — a full push from a stale branch cannot quietly undo a reviewer's work.

Step 4 — Translate

Open Estate ▸ Localize in Vibgrate Cloud. The Keys tab lists every key with its source text and the translation for the language you pick, filterable by status, and editable in place. The Progress tab shows coverage per language.

Coverage counts accepted translations only. Machine output is reported separately and never counted as done, so a project translated entirely by a model does not look finished.

You can also check coverage without leaving the terminal:

vg locale status

Step 5 — Pull the Results Back

vg locale pull

This writes accepted translations into your locale files, key-sorted, so running it twice produces no second diff. Machine and needs-review entries are left out by default — pass --include-machine if you want them, for example on a preview branch where a rough draft beats an empty string.

Review the diff and commit it like any other change.

Keeping Files Tidy

vg locale format re-reads each locale file and rewrites it key-sorted in the configured format. It is local-only, makes no network call, and works on every plan — useful as a pre-commit hook so hand-edited locale files stay consistent:

vg locale format

Add --dry-run to see which files would change without writing.

Wiring It into CI

Create a token, since interactive sign-in is not available in CI:

vg dsn create

Store it as VIBGRATE_DSN in your CI secrets. Then, on each push to your default branch:

vg locale save-missing

New keys reach your translators as soon as they are merged, and no reviewed translation is ever overwritten.

Related

• vg locale — full command reference
• Authenticating with vg login — browser sign-in
• Create a data source with vg dsn — tokens for CI
• Authenticating the CLI in CI — storing the token in your pipeline
• Command reference — flags and formats in detail