@syedamirali/i18n-toolkit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Syed Amir Ali
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,191 @@
+# i18n-toolkit
+
+AST-based CLI to extract translation keys from a React / Next.js project, diff them against translation resource files, and translate the missing ones via a local Ollama instance.
+
+## Install
+
+```bash
+# global
+npm install -g @syedamirali/i18n-toolkit
+
+# or one-shot via npx (no install)
+npx @syedamirali/i18n-toolkit extract --src ./src
+```
+
+Requires **Node ≥ 20**. For `translate` you also need a running Ollama instance.
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `i18n-toolkit extract` | Scan source for translation keys |
+| `i18n-toolkit diff` | Compare extracted keys against a translation file |
+| `i18n-toolkit translate` | Translate missing keys via Ollama |
+| `i18n-toolkit help` | Show top-level help |
+
+---
+
+## `i18n-toolkit extract`
+
+```bash
+i18n-toolkit extract --src /path/to/your/app/src
+```
+
+Output: `output/{timestamp}_translation_extractor.json` — sorted, deterministic.
+
+**What it matches** (all AST-based, no regex):
+
+| Source | → |
+|---|---|
+| `t("k", { __default__: "v" })` | `{ "k": "v" }` |
+| `t("k") \|\| "fallback"` | `{ "k": "fallback" }` |
+| `t("k")` | `{ "k": "__missing_default__" }` |
+| `<Trans localKey="k">Default</Trans>` | `{ "k": "Default" }` |
+| `<X localKey={\`a.${slug}.b\`}>{name}</X>` | `` { "a.${slug}.b": "__dynamic__" } `` |
+
+**Key options:**
+
+```
+--src <path>             root to scan (default ".")
+--out <path>             explicit output file (overrides --output-dir)
+--output-dir <path>      default ./output
+--log-dir <path>         default ./logs
+--lang <code>            top-level language key (default "en")
+--fail-on-conflict       exit 1 if any key has conflicting defaults
+--help                   full options list
+```
+
+---
+
+## `i18n-toolkit diff`
+
+```bash
+# Scriptable
+i18n-toolkit diff --src /path/to/app/src --resource ./translations.json
+
+# Interactive
+i18n-toolkit diff
+```
+
+`--src` accepts either a directory (runs extraction in-process) or a previously-extracted JSON file.
+`--resource` auto-detects flat `{ key: value }` vs language-wrapped `{ "en": { … } }` and picks the `en` slice.
+
+**Output:** `diff-output/{timestamp}/`
+
+| File | What's in it |
+|---|---|
+| `missing_in_resource.json` | Keys present in code, missing from resource — **translate these** |
+| `missing_in_extractor.json` | Keys present in resource, no longer in code — orphans |
+| `{timestamp}_translation_diff.log` | Run log with absolute paths |
+
+`"__dynamic__"` keys are skipped from comparison. Empty `""` values in either side are treated as missing.
+
+---
+
+## `i18n-toolkit translate`
+
+```bash
+i18n-toolkit translate
+```
+
+Interactive. Three steps:
+
+1. **Input** — pick a recent `missing_in_resource.json`, paste a path, or paste content inline.
+2. **Target languages** — searchable multi-select from `data/languages.json`. The source (`en`) is shown at the top, pinned and disabled.
+3. **Model** — pick from your local Ollama's installed models.
+
+The Ollama call streams with live thinking + response phases and a sticky status footer (elapsed / tokens / KB).
+
+**Output:** `translate-output/{timestamp}/translation.json`
+
+```json
+{
+  "en": { "common.back": "Back",   "common.cart": "Cart"   },
+  "fr": { "common.back": "Retour", "common.cart": "Panier" },
+  "ar": { "common.back": "رجوع",   "common.cart": "عربة"   }
+}
+```
+
+**Env vars:**
+
+```
+OLLAMA_URL           default http://172.25.80.1:11434
+OLLAMA_TIMEOUT_MS    default 1800000 (30 min)
+NO_COLOR             disable ANSI colors
+```
+
+---
+
+## Pipeline
+
+The three commands compose:
+
+```
+your-app/src/  ──extract──▶  output/…json
+                                  │
+                                  ▼
+   resource.json  ──diff──▶  diff-output/…/missing_in_resource.json
+                                                  │
+                                                  ▼
+                                     translate ──▶ translate-output/…/translation.json
+```
+
+Drop the final `translation.json` back into your app's translation resource and the cycle closes.
+
+---
+
+## Local development
+
+Clone the repo, install dependencies, and use the yarn aliases:
+
+```bash
+git clone https://github.com/SyedAmirAli/i18n-toolkit.git
+cd i18n-toolkit
+yarn install
+
+yarn extract -- --src /path/to/your/app/src
+yarn diff -- --src /path/to/app/src --resource ./translations.json
+yarn translate
+
+yarn build       # bundle to dist/ (used by npm publish)
+yarn typecheck   # tsc --noEmit
+```
+
+---
+
+## Project structure
+
+```
+src/
+├── cli.ts           subcommand router (the published bin entry)
+├── index.ts         extract command + runExtraction() programmatic API
+├── diff.ts          diff command
+├── translate.ts     translate command
+└── lib/
+    └── ui.ts        Spinner, StatusFooter, JsonPretty, multilineInput, color helpers
+prompt/              prompt template used by translate
+data/                language list used by translate
+docs/plans/          design docs (one per command)
+dist/                bundled output (generated; not in git)
+```
+
+Generated output dirs (gitignored): `output/`, `logs/`, `diff-output/`, `translate-output/`.
+
+---
+
+## Design docs
+
+See [`docs/plans/`](./docs/plans/) for the full design behind each command.
+
+| Plan | Command |
+|---|---|
+| [01-translation-extractor.plan.md](./docs/plans/01-translation-extractor.plan.md) | `extract` |
+| [02-translation-diff.plan.md](./docs/plans/02-translation-diff.plan.md) | `diff` |
+| [03-translate.plan.md](./docs/plans/03-translate.plan.md) | `translate` |
+| [04-translate-quality.plan.md](./docs/plans/04-translate-quality.plan.md) | `translate` quality detection (planned) |
+
+---
+
+## License
+
+[MIT](./LICENSE) © Syed Amir Ali