CLI reference
Run with npx glotfox <command> from the directory containing glotfox.config.json. Requires Node 22+.
File formats
Locale files are JSON by default. Set output.format to "po" or "yaml" (with a matching output.pattern such as {locale}/{namespace}.po) and extract, check, push, pull and types read and write that format. See the file format spec.
Commands
| Command | Options | What it does |
|---|---|---|
init | --source <locale>, --targets a,b, --force | Writes glotfox.config.json. Refuses to overwrite without --force. |
extract | --dry-run, --force | Scans code and adds new keys to the source-locale files. Never deletes; reports unused keys. --force overwrites existing descriptions in *.meta.json. |
push | --api-url, --dry-run | Uploads source keys and descriptions. Never deletes keys on the server. |
pull | --api-url, --dry-run | Writes approved translations of each target locale into the locale files. Approved text wins; other local keys are kept. |
check | Read-only, for CI. Exits 1 if code uses keys missing from the source files, or the generated types are missing or stale. | |
types | --out <file>, --dry-run | Generates a TypeScript declaration file from the source locale. |
Environment
| Variable | Description |
|---|---|
GLOTFOX_API_KEY | Project API key, required by push and pull. |
GLOTFOX_API_URL | Server URL (default https://glotfox.app.dukauskas.lt). |
What is detected
| Pattern | Notes |
|---|---|
t('key'), i18n.t('key') | String literals only; dynamic keys are ignored. |
t('key', 'Default text') | Default text becomes the source string. |
t('key', { defaultValue, description, ns }) | description goes to <namespace>.meta.json. |
t('key', 'Buy now', { maxLength: 20 }) | maxLength (a positive integer) is sent by push and shown as a character counter in the editor; longer translations are flagged too-long. |
<Trans i18nKey defaults ns /> | Default text from defaults or plain-text children. |
useTranslation('ns'), t('ns:key') | Sets the namespace. |
push also sends the file and line of every usage; they appear under "Used in" on the key's Details tab and are replaced on each push.
Without a default text, the value is set to the key itself and a warning is printed. Placeholder types follow the file format spec.