i18n-hunter 🏹

Hunt down every hardcoded string in your Vue/React project and automate your i18n workflow.

Features

• 🎯 AST-Based Extraction — Uses @vue/compiler-sfc for Vue and @babel/parser for React/JSX to accurately detect user-facing strings — not just any string literal.
• 🔄 Full Workflow CLI — scan → edit JSON → apply → verify → rollback or clean. End-to-end, without touching any tool other than your editor.
• 🧠 Context-Aware Keys — Automatically generates semantic keys like common.btn.save, home.lbl.title, error.msg.network based on surrounding HTML tags.
• 🛡️ Safe by Design — Every apply creates .bak backups and a manifest. One command to rollback all changes.
• 📊 Dual Reports — Exports .json (editable, for key refinement) and .md (human-readable, for review).
• 🔗 Hybrid Projects — Scan Vue and React files in the same run; each file gets the right parser automatically.

Installation

# Global install (recommended for recurring use)
npm install -g i18n-hunter

# Or run without installing
npx i18n-hunter scan --paths src/

Workflow

1. scan     → finds strings, generates report.json
2. (edit)   → manually refine suggestedKey values in report.json
3. apply    → replaces hardcoded strings with t('key') and backs up files
4. (review) → check the changes in your editor / browser
5. clean    → delete backups once confirmed OK  (or rollback if not)

Commands

scan — Find hardcoded strings

i18n-hunter scan --paths src/          # Scan entire directory
i18n-hunter scan --paths src/views/Home.vue,src/components/
i18n-hunter scan --output ./reports    # Custom output directory
i18n-hunter scan --format json         # JSON only (skip Markdown)

Output:

• ./i18n-reports/report.json — editable report with suggestedKey per string
• ./i18n-reports/report.md — human-readable for review or PR description

apply — Replace strings with t('key')

i18n-hunter apply                                    # Apply from default report
i18n-hunter apply --report ./i18n-reports/report.json
i18n-hunter apply --dry-run                          # Preview without writing files

What it does per file:

• Vue: Replaces text with {{ $t('key') }}, attributes with :attr="$t('key')", and injects useI18n if needed.
• React: Replaces text with {t('key')}, attributes with attr={t('key')}, and injects useTranslation at the top of the component.
• Both: Creates a .i18n-hunter.bak backup and records the operation in a manifest.

rollback — Undo all applied changes

i18n-hunter rollback     # Restores all files from .bak backups

Uses the manifest generated by apply to restore every file to its original state.

sync — Sync the Markdown report from JSON

i18n-hunter sync         # Updates report.md from report.json

After manually editing keys in report.json, run sync to regenerate the .md report.

clean — Delete backup files

i18n-hunter clean        # Removes all .bak files and the manifest

Run after you've verified that apply worked correctly.

All Options

| Flag | Commands | Description | Default | |------|----------|-------------|---------| | --paths | scan | Comma-separated files or directories | src/ | | --output | scan | Directory for generated reports | ./i18n-reports | | --format | scan | Output format: json, md, json,md | json,md | | --base | scan, apply | Base root path for resolving relative paths | process.cwd() | | --report | apply | Path to the JSON report file | Auto-detected | | --dry-run | apply | Preview changes without writing files | false |

Example Output

report.json (excerpt):

{
  "results": [
    {
      "filePath": "src/views/Login.vue",
      "lineNumber": 12,
      "hardcodedString": "Sign in to your account",
      "suggestedKey": "login.lbl.signIn",
      "context": "tag:h1",
      "category": "label"
    }
  ]
}

After apply:

<!-- Before -->
<h1>Sign in to your account</h1>

<!-- After -->
<h1>{{ $t('login.lbl.signIn') }}</h1>

Peer Dependencies

i18n-hunter uses optional peer dependencies. Install them only for the frameworks you use:

# For Vue projects
npm install --save-dev @vue/compiler-sfc @vue/compiler-dom

# React/TSX parsing works out of the box (no peer deps needed)

License

MIT © tiepviet