A command-line tool for managing FormatJS translations with POEditor integration
npm install @leancodepl/intlA command-line tool for managing FormatJS translations with POEditor integration. Extracts messages from
TypeScript/React source files, uploads terms to POEditor, downloads translations, and compiles them for use in
internationalized applications.
``sh`
npm install -D @leancodepl/intl
`sh`
npx @leancodepl/intl
Configure POEditor credentials using environment variables:
- POEDITOR_API_TOKEN - POEditor API token (required for upload, download, sync, and diff commands)POEDITOR_PROJECT_ID
- - POEditor project ID (required for upload, download, sync, and diff commands)
Extracts FormatJS messages from source files. When POEditor credentials are provided, merges extracted messages with
downloaded translations for default language. Downloaded translations are not overridden - only new terms added during
development are added to translations file. Use this command during development to fix build errors after adding new
term in code.
Usage:
`sh`
npx @leancodepl/intl local [options]
Options:
- -s, --src-pattern - Source file pattern for extraction (default: "src/*/!(.d).{ts,tsx}")-o, --output-dir
- - Output directory for compiled translations (default: "lang")-d, --default-language
- - Default language for translations (required when using POEditor integration)-t, --poeditor-api-token
- - POEditor API token (overrides POEDITOR_API_TOKEN env var)-p, --poeditor-project-id
- - POEditor project ID (overrides POEDITOR_PROJECT_ID env var)
Extracts FormatJS messages from source files and uploads both terms and default language translations to POEditor.
Usage:
`sh`
npx @leancodepl/intl upload [options]
Options:
- -s, --src-pattern - Source file pattern for extraction (default: "src/*/!(.d).{ts,tsx}")-d, --default-language
- - Default language for translations (required)-t, --poeditor-api-token
- - POEditor API token (overrides POEDITOR_API_TOKEN env var, required)-p, --poeditor-project-id
- - POEditor project ID (overrides POEDITOR_PROJECT_ID env var, required)
Downloads translations from POEditor for specified languages and compiles them to JSON files.
Usage:
`sh`
npx @leancodepl/intl download [options]
Options:
- -o, --output-dir
- Output directory for compiled translations (default: "lang")
- -l, --languages - Languages to download (space-separated list, required)
- -t, --poeditor-api-token - POEditor API token (overrides POEDITOR_API_TOKEN env var, required)
- -p, --poeditor-project-id - POEditor project ID (overrides POEDITOR_PROJECT_ID env var, required)$3
Combines upload and download operations. Uploads extracted terms and default language translations to POEditor, then
downloads and compiles translations for specified languages.
Usage:
`sh
npx @leancodepl/intl sync [options]
`Options:
-
- Source file pattern for extraction (default: "src/*/!(.d).{ts,tsx}")
- -o, --output-dir - Output directory for compiled translations (default: "lang")
- -l, --languages - Languages to download (space-separated list, required)
- -d, --default-language - Default language for translations (required)
- -t, --poeditor-api-token - POEditor API token (overrides POEDITOR_API_TOKEN env var, required)
- -p, --poeditor-project-id - POEditor project ID (overrides POEDITOR_PROJECT_ID env var, required)$3
Compares locally extracted terms with POEditor terms to identify unused terms in the translation service. Helps maintain
clean translation projects by finding orphaned entries.
Usage:
`sh
npx @leancodepl/intl diff [options]
`Options:
-
- Source file pattern for extraction (default: "src/*/!(.d).{ts,tsx}")
- -t, --poeditor-api-token - POEditor API token (overrides POEDITOR_API_TOKEN env var, required)
- -p, --poeditor-project-id - POEditor project ID (overrides POEDITOR_PROJECT_ID env var, required)Nx Configuration
Configure intl commands as Nx target in your
project.json. Example configuration:`json
"intl": {
"executor": "nx:run-commands",
"defaultConfiguration": "local",
"configurations": {
"local": {
"command": "npx @leancodepl/intl local --src-pattern 'src/*/!(.d).{ts,tsx}' --output-dir '{projectRoot}/lang' --default-language pl --poeditor-project-id 123456"
},
"download": {
"command": "npx @leancodepl/intl download --output-dir '{projectRoot}/lang' --languages pl en --poeditor-project-id 123456"
},
"diff": {
"command": "npx @leancodepl/intl diff --src-pattern 'src/*/!(.d).{ts,tsx}' --poeditor-project-id 123456"
},
"upload": {
"command": "npx @leancodepl/intl upload --src-pattern 'src/*/!(.d).{ts,tsx}' --default-language pl --poeditor-project-id 123456"
},
"sync": {
"command": "npx @leancodepl/intl sync --src-pattern 'src/*/!(.d).{ts,tsx}' --output-dir '{projectRoot}/lang' --languages pl en --default-language pl --poeditor-project-id 123456"
}
}
}
`Local Development
To simplify local development tests can be used with real POEditor integration.
$3
#### Run tests with POEditor integration
Set the following environment variables:
-
: Your POEditor API token
- POEDITOR_PROJECT_ID: Your POEditor project IDTo run specific command run only test for that command. Example for
local command:`bash
POEDITOR_API_TOKEN=your_token POEDITOR_PROJECT_ID=your_project_id npx nx test intl -- local.spec.ts
`Tests will use predefined test project for extracting example messages and will save outputs in
. Be careful with running sync and upload` commands. Terms extracted from example