i18n-saas-cli

The official Command Line Interface for the i18n-saas platform.

This CLI tool automatically scans your source code for translation keys (e.g., t('auth.login'), $t('button.submit', { count: 1 })) and synchronizes them directly with your i18n-saas project. It saves you the hassle of manually creating translation keys in the web interface!

Quick Start

You don't need to install the package globally. You can use npx to run it directly:

npx i18n-saas-cli <command> [directory] [options]

Commands

1. sync (Synchronize with i18n-saas API)

Scans your source code for translation keys and local translation files, then uploads and synchronizes them directly with your i18n-saas project.

npx i18n-saas-cli sync ./src --project-id=YOUR_PROJECT_ID --token=YOUR_API_TOKEN

2. info (Translation Statistics)

Scans your source code and local translation files, displaying a complete breakdown of translation coverage per locale. Does not send data to the server.

npx i18n-saas-cli info .

3. check (Lint Missing Translations for CI/CD)

Checks for missing translations per language. Outputs the exact list of missing keys and exits with code 1 if any keys are missing. Perfect for GitHub Actions or CI/CD pipelines!

npx i18n-saas-cli check .

Key Features & Key Extraction

• Supported Functions: t(), $t(), this.$t(), i18n.t(), tc(), $tc(), te(), $te(), translate().
• String Literals: Single quotes 'key', double quotes "key", or backticks `key`.
• Multiple Arguments: Supports interpolation parameters e.g., $t('auth.login', { user: name }).
• False Positive Protection: Smart word boundary matching prevents false matches from functions ending in t (e.g. format(), concat(), select()).
• Dynamic Expression Filtering: Dynamic template strings with interpolation (e.g. $t(`status.${type}`)) are safely ignored to avoid false missing key reports.

Translation Files & Directory Detection

The CLI automatically detects existing translation files in your project:

• Supported Folder Names: locales, locale, lang, langs, i18n, translations, messages (e.g. src/langs, locales/, src/i18n).
• Supported File Formats:
  • Pure JSON (.json)
  • JavaScript / TypeScript object exports (.js, .ts, .mjs, .cjs) e.g. export default { ... } or module.exports = { ... }.
  • Vue Single File Components (SFC) inline <i18n> custom blocks (e.g. <i18n lang="json"> ... </i18n>).
• Nested Subdirectories: Supports arbitrary folder nesting inside locale directories!
  • langs/uk/enums/document-status.json $\rightarrow$ automatically assigned locale uk and key prefix enums.document-status.*.
• Ignored Directories: Automatically ignores node_modules, .git, .nuxt, .next, dist, build, .idea.

Options & Flags

| Flag | Description | Example | | :--- | :--- | :--- | | --project-id=<id> | Required for sync. Your i18n-saas Project ID. | --project-id=prj_123 | | --token=<token> | Required for sync. Your API Token. | --token=tok_abc123 | | --url=<url> | Optional base API URL (default: https://api.i18n-saas.com). | --url=https://api.my-domain.com | | --locales-dir=<dir> | Explicitly set the locales directory path or folder name. | --locales-dir=src/langs | | --ignore=<items> | Comma-separated list of paths or keywords to ignore. | --ignore=legacy,vendor |

Supported Source File Extensions

The CLI extracts translation keys from:

• .vue (Vue 2 & Vue 3)
• .js, .jsx, .ts, .tsx (React, Next.js, Nuxt, Node.js)
• .go (Golang)
• .html

License

MIT