@pico-intl-dev/cli

CLI tooling for pico-intl locale workflows.

Status: stable v1 for file-based locale workflows covered by the CLI E2E and snapshot suites. Provider-backed machine translation remains beta and AI output should always be reviewed before merging.

The CLI is pico-intl's primary production differentiator. Runtime performance is measured, but real localization work is won or lost in extraction, validation, generated types, migration, CI, and reviewed translation flows.

Install

npm install --save-dev @pico-intl-dev/cli

Or run through npx:

npx pico-intl --help

Common commands

pico-intl init --base en --targets es,fr
pico-intl validate --strict
pico-intl generate --output ./src/generated
pico-intl extract --src ./src --dry-run
pico-intl check --src ./src --strict --complete
pico-intl doctor --src ./src --ci
pico-intl stats --json
pico-intl prune --src ./src --dry-run

Recommended pull request loop:

pico-intl extract --src ./src --dry-run
pico-intl check --src ./src --strict --complete
pico-intl doctor --src ./src --ci
pico-intl doctor --src ./src --ci --json
pico-intl generate --output ./src/generated
pico-intl stats --threshold 90

Migration helpers

pico-intl import --from i18next --input ./src/locales --output ./locales
pico-intl import --from lingui --input ./src/locales --output ./locales
pico-intl export --to react-intl --output ./translations
pico-intl import --from react-intl --input ./translations --output ./locales --report
pico-intl export --to xliff --output ./tms-upload
pico-intl import --from xliff --input ./tms-download --output ./locales

Import supports i18next, react-intl, Lingui JSON catalogs, vue-i18n, Fluent, gettext PO, and XLIFF 1.2. Export supports i18next, react-intl, vue-i18n, Fluent, gettext PO, Flutter ARB, and XLIFF 1.2 for TMS workflows such as Crowdin, Lokalise, Transifex, and Weblate. Complex syntax and app-specific conventions should be reviewed after migration.

import --report writes migration-report.json with ICU-lite compatibility warnings such as rich text tags, plural offsets, exact plural selectors, and nested ICU risk.

For human translation platforms, use file-based XLIFF exchange: export --to xliff, upload the generated .xlf files, download translated .xlf files, then import --from xliff and run doctor --ci.

Message syntax mode

The default CLI mode follows pico-intl core's ICU-lite syntax. Projects that opt into @pico-intl-dev/messageformat can enable full ICU tooling without changing the plain JSON catalog shape:

{
  "messageSyntax": "messageformat"
}

In messageformat mode, validate and doctor fail invalid ICU MessageFormat strings, generate infers params from nested plural/select/date/number messages, and translate protects ICU variables and structure before writing provider output.

Translation providers

pico-intl translate --to es,fr --provider openai --dry-run

Provider configuration is read from pico-intl.config.json. OpenAI options include configurable model, base URL, product context, glossary terms, and a request timeout guard.

pico-intl translate --to es --provider openai --context "B2B billing dashboard" --glossary "workspace=espacio de trabajo" --cache

Config example:

{
  "provider": "openai",
  "openaiModel": "gpt-4o-mini",
  "openaiBaseUrl": "https://api.openai.com/v1",
  "translationContext": "B2B billing dashboard",
  "glossary": {
    "workspace": "espacio de trabajo"
  },
  "translationCacheFile": "./.pico-intl/translate-cache.json",
  "translationReviewFile": "./.pico-intl/translation-review.json"
}

Provider-backed translation is a draft workflow. Placeholder preservation, context/glossary prompts, and source-hash caching are covered by deterministic paths, but generated copy still requires human review. Generated provider output is tracked in .pico-intl/translation-review.json as draft; pico-intl doctor --src ./src --ci blocks while drafts remain. Mark entries as reviewed only after human review.

translate also treats the provider contract as strict: if a provider throws, loses placeholders, or returns a different number of translations than requested, the command fails and does not write the affected locale file. Successful target locales still record review entries even if a later target fails.

CI health gate

Use doctor when you want one release-oriented report:

pico-intl doctor --src ./src --ci
pico-intl doctor --src ./src --ci --json

The report covers source keys, target locale completeness, placeholder parity, message syntax checks, coverage thresholds, and provider-generated translation drafts.

Production notes

• File writes use atomic helpers where commands modify locale/config output.
• Use --dry-run for extraction, pruning, and provider-backed translation before writing changes.
• Use generated translation types in application code for serious projects.
• Treat generated translations as draft content unless reviewed by a fluent speaker or localization process.

Verification

npm run build:cli
npm test