{"_id":"@ddongule/i18n-mcp","_rev":"3-c09e0a65164e245a0cb09ae50cbee348","name":"@ddongule/i18n-mcp","dist-tags":{"latest":"1.1.0"},"versions":{"1.0.0":{"name":"@ddongule/i18n-mcp","version":"1.0.0","_id":"@ddongule/i18n-mcp@1.0.0","maintainers":[{"name":"ddongule","email":"mnk918p@gmail.com"}],"dist":{"shasum":"23c0b22c57e47163fb9253745ee081d14743ed89","tarball":"https://registry.npmjs.org/@ddongule/i18n-mcp/-/i18n-mcp-1.0.0.tgz","fileCount":2,"integrity":"sha512-5gvtZ0lfei+GA8HxhUlBLTJeQJdbOSg1DyxGI4oyESG/CJlQShbfU++k1l0BsPhLJ604dkIrLs7MyFXQHh8kcA==","signatures":[{"sig":"MEUCIEAlbZOa/clNpuwtT0J0vr8n0vT3YhQaxof+W4kKmbBFAiEAi+LJ/TlnaeNZhvp0e0YSGTtHD1sH1LsgaHetsdI/FB0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":5773},"main":"dist/index.js","gitHead":"ce1299ae8ee20b410efac4e8bf41d4cc1b7ed8d8","private":false,"scripts":{"build":"tsc"},"_npmUser":{"name":"ddongule","email":"mnk918p@gmail.com"},"_npmVersion":"10.8.2","description":"An MCP (Model Context Protocol) server that exposes i18n automation as **AI-callable tools**.","directories":{},"_nodeVersion":"20.19.3","dependencies":{"i18n-core":"workspace:*","@modelcontextprotocol/sdk":"^0.x"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/i18n-mcp_1.0.0_1767628599848_0.1478303369514482","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@ddongule/i18n-mcp","version":"1.0.1","keywords":["mcp","i18n"],"author":{"name":"ddongule"},"license":"MIT","_id":"@ddongule/i18n-mcp@1.0.1","maintainers":[{"name":"ddongule","email":"mnk918p@gmail.com"}],"homepage":"https://github.com/ddongule/i18n#readme","bugs":{"url":"https://github.com/ddongule/i18n/issues"},"dist":{"shasum":"59dd449b7d3ca18f8944dda25678e2875b6bcc76","tarball":"https://registry.npmjs.org/@ddongule/i18n-mcp/-/i18n-mcp-1.0.1.tgz","fileCount":2,"integrity":"sha512-h2JjYQWEg5Sg4aXJhF6ZN/8xaZlijP2AeDafRoXeZXl8bGRc49cKKKH9PFy/UmO4/gwqXZEv4P2+rocI0Goufg==","signatures":[{"sig":"MEYCIQDJGkeCHEsi/qacX2CN72HB8/QnV7GloXnqVQPWFxK3dQIhAI4T8YfWgm9ZQLdjp70OvIRFbPBt+RsevM032/RkseqE","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":6018},"main":"dist/index.js","gitHead":"ce1299ae8ee20b410efac4e8bf41d4cc1b7ed8d8","private":false,"scripts":{"build":"tsc"},"_npmUser":{"name":"ddongule","email":"mnk918p@gmail.com"},"repository":{"url":"git+https://github.com/ddongule/i18n.git","type":"git"},"_npmVersion":"10.8.2","description":"An MCP (Model Context Protocol) server that exposes i18n automation as **AI-callable tools**.","directories":{},"_nodeVersion":"20.19.3","dependencies":{"i18n-core":"workspace:*","@modelcontextprotocol/sdk":"^0.x"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/i18n-mcp_1.0.1_1767628850951_0.39512652463321496","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@ddongule/i18n-mcp","author":{"name":"ddongule"},"version":"1.1.0","private":false,"type":"module","bin":{"i18n-mcp":"dist/index.js"},"main":"dist/index.js","repository":{"type":"git","url":"git+https://github.com/ddongule/i18n.git"},"bugs":{"url":"https://github.com/ddongule/i18n/issues"},"keywords":["mcp","i18n","model-context-protocol","localization","translation"],"license":"MIT","dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","glob":"^13.0.0","googleapis":"^169.0.0","xlsx":"^0.18.5","zod":"^3.25.0"},"devDependencies":{"@types/node":"^25.0.3","tsup":"^8.5.0","typescript":"^5.9.3","i18n-mcp-core":"1.0.0"},"scripts":{"build":"tsup","start":"node dist/index.js"},"_id":"@ddongule/i18n-mcp@1.1.0","description":"An MCP (Model Context Protocol) server that exposes i18n automation as **AI-callable tools**.","homepage":"https://github.com/ddongule/i18n#readme","_integrity":"sha512-Gz4RVdX1gplqhsp9FFgzxDWbIZSpY8zREXLF+nVF12WdA6wqRhKmq+QKDzvxKnEk9S66waX0CBDx4LAVb9qERw==","_resolved":"/private/var/folders/wt/b4hqyyk164sgt3vvkst_8dmc0000gn/T/3aa383ad7822a6df56f6c17096a75bf9/ddongule-i18n-mcp-1.1.0.tgz","_from":"file:ddongule-i18n-mcp-1.1.0.tgz","_nodeVersion":"20.19.3","_npmVersion":"10.8.2","dist":{"integrity":"sha512-Gz4RVdX1gplqhsp9FFgzxDWbIZSpY8zREXLF+nVF12WdA6wqRhKmq+QKDzvxKnEk9S66waX0CBDx4LAVb9qERw==","shasum":"cea92f4cd527536f0a56d87936109c13b7fdba27","tarball":"https://registry.npmjs.org/@ddongule/i18n-mcp/-/i18n-mcp-1.1.0.tgz","fileCount":3,"unpackedSize":32683,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQD4NT1QP0qMU5Rp9y21eMa/SEOeQd34HXMf3V2GqSBZJQIgMogARPQnxA8SQQi0f0FePqxVYrqFLkRm3rOGaxAtOwk="}]},"_npmUser":{"name":"ddongule","email":"mnk918p@gmail.com"},"directories":{},"maintainers":[{"name":"ddongule","email":"mnk918p@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/i18n-mcp_1.1.0_1783222188890_0.14586770439044439"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-05T15:56:39.716Z","modified":"2026-07-05T03:29:49.153Z","1.0.0":"2026-01-05T15:56:39.990Z","1.0.1":"2026-01-05T16:00:51.098Z","1.1.0":"2026-07-05T03:29:49.046Z"},"bugs":{"url":"https://github.com/ddongule/i18n/issues"},"author":{"name":"ddongule"},"license":"MIT","homepage":"https://github.com/ddongule/i18n#readme","keywords":["mcp","i18n","model-context-protocol","localization","translation"],"repository":{"type":"git","url":"git+https://github.com/ddongule/i18n.git"},"description":"An MCP (Model Context Protocol) server that exposes i18n automation as **AI-callable tools**.","maintainers":[{"name":"ddongule","email":"mnk918p@gmail.com"}],"readme":"# i18n-mcp\n\nAn MCP (Model Context Protocol) server that exposes i18n automation as **AI-callable tools**.\n\nIt exposes both **AI-callable tools** and **read-only resources** so an agent can\nunderstand a project's i18n state once per session instead of re-scanning every time.\n\nUse it when you want ChatGPT/Cursor/Claude (or other MCP clients) to:\n\n- **Scan** i18n health\n- **Fix** missing/unused keys safely\n- **Import / export** translations from Google Sheets\n- (Optional) **Create PRs** with changes\n- **Read** locale, namespace, and sync-status context as resources\n\n> Published as **`@ddongule/i18n-mcp`**. This package is for AI integrations and\n> requires an MCP client setup. If you just want a normal CLI, use **@ddongule/i18n-cli**.\n\n---\n\n## Table of Contents\n\n- [What is MCP?](#what-is-mcp)\n- [Install](#install)\n- [Run Locally](#run-locally)\n- [Client Setup](#client-setup)\n  - [ChatGPT Desktop](#chatgpt-desktop)\n  - [Cursor](#cursor)\n  - [Claude Desktop](#claude-desktop)\n- [Tools](#tools)\n  - [scan_i18n](#scan_i18n)\n  - [fix_i18n](#fix_i18n)\n  - [import_i18n_from_sheet](#import_i18n_from_sheet)\n  - [export_i18n_to_sheet](#export_i18n_to_sheet)\n  - [create_i18n_pr](#create_i18n_pr)\n- [Resources](#resources)\n- [Configuration](#configuration)\n- [Recommended Workflows](#recommended-workflows)\n- [Google Sheets Credentials](#google-sheets-credentials)\n- [Security Notes](#security-notes)\n- [Troubleshooting](#troubleshooting)\n\n---\n\n## What is MCP?\n\nMCP is a standard way for AI clients to discover and call local tools.\nYou run a small “server” process that advertises tools (with JSON schemas),\nand the AI client can call them with structured arguments.\n\nIn practice:\n\n- You run `i18n-mcp` locally (or in a controlled environment)\n- Your MCP client connects to it\n- The AI can run tools like `fix_i18n` and read tool results\n\n---\n\n## Install\n\nUse `npx`:\n\n```bash\nnpx @ddongule/i18n-mcp\n```\n\nOr install:\n\n```bash\npnpm add -D @ddongule/i18n-mcp\n```\n\n---\n\n## Run Locally\n\nMost MCP clients use stdio transport, so you typically just point the client to:\n\n```bash\nnpx @ddongule/i18n-mcp\n```\n\n---\n\n## Client Setup\n\n### ChatGPT Desktop\n\nExample MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"i18n-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@ddongule/i18n-mcp\"]\n    }\n  }\n}\n```\n\n### Cursor\n\nIn Cursor MCP settings:\n\n```json\n{\n  \"mcpServers\": {\n    \"i18n-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@ddongule/i18n-mcp\"]\n    }\n  }\n}\n```\n\n### Claude Desktop\n\nExample:\n\n```json\n{\n  \"mcpServers\": {\n    \"i18n-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@ddongule/i18n-mcp\"]\n    }\n  }\n}\n```\n\n> Config locations differ by client/version. The key idea is to run `npx @ddongule/i18n-mcp` via stdio.\n\n---\n\n## Tools\n\n### scan_i18n\n\nScan the project and report keys that are **missing** from the base locale or\n**unused** by the code. Read-only.\n\n**Input**\n\n- `baseLang` (string, default `en`)\n\n**Example**\n\n```json\n{ \"name\": \"scan_i18n\", \"arguments\": { \"baseLang\": \"en\" } }\n```\n\n---\n\n### fix_i18n\n\nScan and optionally fix locale files.\n\n**Input**\n\n- `baseLang` (string, default `en`)\n- `deleteUnused` (boolean, default `false`)\n- `createMissing` (boolean, default `false`)\n- `fixStructure` (boolean, default `false`)\n- `locale` (string, optional)\n- `apply` (boolean, default `false`) — when false, behaves like dry-run\n- `backup` (boolean, default `false`) — back up locale files before writing (only when `apply=true`)\n\n**Example**\n\n```json\n{\n  \"name\": \"fix_i18n\",\n  \"arguments\": {\n    \"baseLang\": \"en\",\n    \"deleteUnused\": true,\n    \"createMissing\": true,\n    \"fixStructure\": true,\n    \"apply\": false\n  }\n}\n```\n\n---\n\n### import_i18n_from_sheet\n\nImport translations into `./locales` from Google Sheets.\n\n**Input**\n\n- `sheetId` (string, required)\n- `sheetName` (string, default `Sheet1`)\n- `dryRun` (boolean, default `false`)\n\n**Example**\n\n```json\n{\n  \"name\": \"import_i18n_from_sheet\",\n  \"arguments\": {\n    \"sheetId\": \"1L7h7Ra3hrOrp5MW7_uWV6ANNrBF0b9CgSfJ9hXy7D7w\",\n    \"sheetName\": \"Translations\",\n    \"dryRun\": true\n  }\n}\n```\n\n---\n\n### export_i18n_to_sheet\n\nExport locale JSON files to Google Sheets.\n\n**Input**\n\n- `sheetId` (string, required)\n- `sheetName` (string, default `Sheet1`)\n- `localesDir` (string, optional; default `./locales`)\n- `dryRun` (boolean, default `false`)\n\n**Example**\n\n```json\n{\n  \"name\": \"export_i18n_to_sheet\",\n  \"arguments\": {\n    \"sheetId\": \"1L7h7Ra3hrOrp5MW7_uWV6ANNrBF0b9CgSfJ9hXy7D7w\",\n    \"sheetName\": \"Translations\",\n    \"dryRun\": true\n  }\n}\n```\n\n---\n\n### create_i18n_pr\n\nCreate a GitHub pull request for locale changes.\n\n**Recommended guards (v1)**\n\n- If dry-run mode was used: **do not create a PR**\n- If there are **no changes**: **do not create a PR**\n- If `gh` CLI is missing: show a clear error message\n\n**Input**\n\n- `title` (string, default `chore(i18n): fix translations`)\n- `body` (string)\n- `branch` (string, default `i18n/auto-fix`)\n\nCommits the `locales` directory and opens a PR against `main`.\n\n---\n\n## Resources\n\nRead-only context an agent can load **once per session** instead of re-scanning\nevery time. All return `application/json`.\n\n### `i18n://locales`\n\nLocale files present in the project and their key counts.\n\n```json\n{ \"localesDir\": \"…/locales\", \"locales\": [ { \"locale\": \"en\", \"keyCount\": 120 }, { \"locale\": \"ko\", \"keyCount\": 118 } ] }\n```\n\n### `i18n://namespaces`\n\nTop-level translation-key namespaces of the base locale.\n\n```json\n{ \"baseLang\": \"en\", \"totalKeys\": 120, \"namespaces\": [ { \"namespace\": \"home\", \"keyCount\": 8 }, { \"namespace\": \"settings\", \"keyCount\": 15 } ] }\n```\n\n### `i18n://status`\n\nCurrent missing / unused / out-of-sync summary from a fresh scan.\n\n```json\n{ \"baseLang\": \"en\", \"totalLocaleKeys\": 120, \"totalCodeKeys\": 122, \"missingCount\": 2, \"unusedCount\": 0, \"inSync\": false, \"missingKeys\": [\"profile.logout.button\"], \"unusedKeys\": [] }\n```\n\n---\n\n## Configuration\n\nThe server operates on the client's working directory. Defaults can be\noverridden with environment variables:\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `I18N_LOCALES_DIR` | `./locales` | Directory holding locale JSON files (absolute or relative to cwd) |\n| `I18N_BASE_LANG` | `en` | Base/reference locale |\n\n```json\n{\n  \"mcpServers\": {\n    \"i18n-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@ddongule/i18n-mcp\"],\n      \"env\": { \"I18N_LOCALES_DIR\": \"src/locales\", \"I18N_BASE_LANG\": \"en\" }\n    }\n  }\n}\n```\n\n---\n\n## Recommended Workflows\n\n### Workflow A: Safe AI-assisted review\n\n1. `fix_i18n` with `apply=false`\n2. AI explains proposed changes\n3. Human approves\n4. `fix_i18n` with `apply=true`\n5. `create_i18n_pr`\n\n### Workflow B: Import from sheet\n\n1. `import_i18n_from_sheet` with `dryRun=true`\n2. Review preview\n3. `import_i18n_from_sheet` with `dryRun=false`\n4. `create_i18n_pr`\n\n---\n\n## Google Sheets Credentials\n\nUse a Service Account JSON key:\n\n- Create a Google Cloud project\n- Create a Service Account\n- Create a JSON key\n- Save it locally: `./credentials/google-service-account.json`\n\nShare the spreadsheet with the service account email (`client_email`) as Viewer (import) or Editor (export).\n\n---\n\n## Security Notes\n\n- The MCP server runs locally with filesystem access.\n- Store credentials outside your repo and add them to `.gitignore`.\n- If you enable PR creation, it runs `git` and `gh` commands—use only in trusted repos.\n\n---\n\n## Troubleshooting\n\n### “gh not found”\n\nInstall GitHub CLI and authenticate:\n\n```bash\ngh auth login\n```\n\n### “Unable to parse range”\n\nYour `sheetName` is wrong; use the correct tab name.\n\n---\n\n## License\n\nMIT\n","readmeFilename":"README.md"}