i18ntk
Version:
i18n Tool Kit - Zero-dependency internationalization toolkit for setup, scanning, analysis, validation, auto translation, fixing, reporting, and runtime translation loading.
269 lines (268 loc) • 23.3 kB
JSON
{
"name": "i18ntk",
"version": "5.0.0",
"description": "i18n Tool Kit - Zero-dependency internationalization toolkit for setup, scanning, analysis, validation, auto translation, fixing, reporting, and runtime translation loading.",
"readmeFilename": "README.md",
"keywords": [
"i18ntk",
"i18n",
"i18n toolkit",
"i18n tool kit",
"internationalization",
"localization",
"translation",
"auto-translation",
"google-translate",
"l10n",
"multilingual",
"i18next",
"react-i18next",
"vue-i18n",
"angular-i18n",
"next-i18next",
"nodejs",
"javascript",
"typescript",
"cli",
"command-line",
"developer-tools",
"translation-management",
"framework-detection",
"zero-dependency",
"security",
"json"
],
"homepage": "https://github.com/vladnoskv/i18ntk#readme",
"bugs": {
"url": "https://github.com/vladnoskv/i18ntk/issues"
},
"repository": {
"type": "git",
"url": "git+https://github.com/vladnoskv/i18ntk.git"
},
"funding": {
"type": "individual",
"url": "https://www.charitynavigator.org/"
},
"license": "SEE LICENSE IN LICENSE",
"author": {
"name": "Vlad Noskov",
"url": "https://github.com/vladnoskv"
},
"type": "commonjs",
"main": "main/manage/index.js",
"types": "runtime/i18ntk.d.ts",
"exports": {
".": "./main/manage/index.js",
"./runtime": {
"types": "./runtime/index.d.ts",
"require": "./runtime/index.js",
"default": "./runtime/index.js"
},
"./runtime/enhanced": {
"types": "./runtime/enhanced.d.ts",
"require": "./runtime/enhanced.js",
"default": "./runtime/enhanced.js"
},
"./runtime/*": "./runtime/*",
"./report": "./utils/report-model.js",
"./license-marker": "./utils/license-marker.js",
"./ui-locales/*": "./ui-locales/*",
"./package.json": "./package.json"
},
"bin": {
"i18ntk": "main/manage/index.js",
"i18ntk-setup": "main/i18ntk-setup.js",
"i18ntk-manage": "main/manage/index.js",
"i18ntk-init": "main/i18ntk-init.js",
"i18ntk-analyze": "main/i18ntk-analyze.js",
"i18ntk-validate": "main/i18ntk-validate.js",
"i18ntk-usage": "main/i18ntk-usage.js",
"i18ntk-complete": "main/i18ntk-complete.js",
"i18ntk-sizing": "main/i18ntk-sizing.js",
"i18ntk-summary": "main/i18ntk-summary.js",
"i18ntk-doctor": "main/i18ntk-doctor.js",
"i18ntk-report": "main/i18ntk-report.js",
"i18ntk-fixer": "main/i18ntk-fixer.js",
"i18ntk-scanner": "main/i18ntk-scanner.js",
"i18ntk-backup": "main/i18ntk-backup.js",
"i18ntk-translate": "main/i18ntk-translate.js",
"i18ntk-license": "main/i18ntk-license.js"
},
"files": [
"main/i18ntk-analyze.js",
"main/i18ntk-backup-class.js",
"main/i18ntk-backup.js",
"main/i18ntk-translate.js",
"main/i18ntk-complete.js",
"main/i18ntk-doctor.js",
"main/i18ntk-fixer.js",
"main/i18ntk-init.js",
"main/i18ntk-license.js",
"main/i18ntk-scanner.js",
"main/i18ntk-setup.js",
"main/i18ntk-report.js",
"main/i18ntk-sizing.js",
"main/i18ntk-summary.js",
"main/i18ntk-ui.js",
"main/i18ntk-usage.js",
"main/i18ntk-validate.js",
"main/i18ntk-go.js",
"main/i18ntk-java.js",
"main/i18ntk-js.js",
"main/i18ntk-php.js",
"main/i18ntk-py.js",
"main/manage/",
"runtime/",
"settings/language-config.json",
"settings/framework-templates.json",
"settings/settings-cli.js",
"settings/settings-manager.js",
"ui-locales/",
"skills/i18ntk/",
"utils/admin-auth.js",
"utils/admin-cli.js",
"utils/cli-helper.js",
"utils/cli.js",
"utils/colors-new.js",
"utils/config-helper.js",
"utils/config-manager.js",
"utils/config.js",
"utils/env-manager.js",
"utils/exit-codes.js",
"utils/extractor-manager.js",
"utils/extractors/regex.js",
"utils/english-placeholder-checker.js",
"utils/format-manager.js",
"utils/formats/json.js",
"utils/translate/placeholder.js",
"utils/translate/api.js",
"utils/translate/safe-network.js",
"utils/translate/traverse.js",
"utils/translate/report.js",
"utils/translate/cli.js",
"utils/translate/protection.js",
"utils/translation-quality.js",
"utils/framework-detector.js",
"utils/framework-config-templates.js",
"utils/i18n-helper.js",
"utils/init-helper.js",
"utils/json-output.js",
"utils/localized-confirm.js",
"utils/mini-commander.js",
"utils/locale-optimizer.js",
"utils/language-menu.js",
"utils/skill-installer.js",
"utils/language-registry.js",
"utils/license-marker.js",
"utils/locale-discovery.js",
"utils/logger.js",
"utils/menu-layout.js",
"utils/npm-version-warning.js",
"utils/plugin-loader.js",
"utils/prompt-helper.js",
"utils/prompt.js",
"utils/promptPin.js",
"utils/report-writer.js",
"utils/report-model.js",
"utils/secure-errors.js",
"utils/security.js",
"utils/setup-enforcer.js",
"utils/terminal-icons.js",
"utils/usage-source.js",
"utils/usage-insights.js",
"utils/validation-risk.js",
"utils/version-utils.js",
"utils/watch-locales.js",
"LICENSE",
"COMMERCIAL-LICENSE.md",
"README.md",
"CHANGELOG.md",
"docs/reliability.md",
"docs/migration-v4-to-v5.md",
"docs/framework-templates.md",
"CODE_OF_CONDUCT.md",
"CONTRIBUTING.md",
"FUNDING.md",
"SECURITY.md"
],
"sideEffects": false,
"engines": {
"node": ">=16.0.0",
"npm": ">=8.0.0"
},
"publishConfig": {
"access": "public"
},
"preferGlobal": true,
"versionInfo": {
"version": "5.0.0",
"releaseDate": "07/11/2026",
"lastUpdated": "07/11/2026",
"maintainer": "Vlad Noskov",
"changelog": "./CHANGELOG.md",
"documentation": "./README.md",
"apiReference": "./docs/api/API_REFERENCE.md",
"majorChanges": [
"BUG FIX: LANGUAGE_CONFIG expanded from 21 to 61 languages with comprehensive ISO 639-1 coverage. All common languages now display their native names in init output instead of 'Unknown'.",
"BUG FIX: defaultLanguages no longer silently truncates to 5 when the config value is an empty array or null. A validation guard preserves the caller's configured list.",
"BUG FIX: Auto Translate now exits 0 on success even when residual untranslated values exist (placeholders, branded terms, short labels). Only real failures (0 translated with >0 total) now produce non-zero exit codes.",
"BUG FIX: supportedExtensions is no longer unconditionally overridden by the format adapter during init. Users who configure extensions in .i18ntk-config keep them.",
"BUG FIX: allowedEnglishTerms now unifies between validation-risk.js and project config. resolveAllowedEnglishTerms() accepts both inline options and project-level .i18ntk-config terms as fallback sources.",
"FRAMEWORK DETECTION: Added 10 new framework detections — Rust, Remix, Gatsby, Astro, Qwik, SolidJS, Ember, React Native, Expo, Ionic. Centralized into framework-detector.js as single source of truth.",
"FILE EXTENSIONS: Added .astro, .mdx, .mjs, .mts, .cjs, .cts, .rs to all file scan lists via centralized SOURCE_EXTENSIONS and SCANNER_EXTENSIONS.",
"ICU/FLUENT PLACEHOLDER SUPPORT: Fluent $variable and ICU MessageFormat patterns added to placeholder detection and comparison.",
"JSX COMPONENT DETECTION: <Trans>, <FormattedMessage>, <Translate> JSX components detected in both VS Code extensions.",
"COMPREHENSIVE TESTING: All 384+ tests pass across CLI, Workbench, and Lens packages.",
"FRAMEWORK DETECTION v2: Added 13 additional FRAMEWORK_PATTERNS (i18ntk-runtime, nuxt, formatjs, lingui, ngx-translate, next-intl, svelte-i18n, solid-i18n, fastapi, ruby-on-rails, react-native-localize, ionic). Expanded detectFramework() to check Python/Rust/Go/Ruby project files. Added 20+ WRAPPER_SKIP_PATTERNS. Added 8 missing FRAMEWORK_COMPATIBILITY versions. Now supports 30+ frameworks across 15+ languages.",
"UI LOCALE EXPANSION: Expanded from 7 to 23 languages (Italian, Portuguese, Dutch, Polish, Swedish, Ukrainian, Czech, Turkish, Korean, Arabic, Hindi, Thai, Vietnamese, Hebrew, Greek, Hungarian). All 2,211 keys auto-translated with placeholder preservation. Native language names in all locale files. getAvailableLanguages(), settings schema enums, and UI language picker expanded to 23. 95-98% translated per language, 0 missing keys.",
"FRAMEWORK DETECTION CLEANUP: manage/index.js now uses centralized detectProjectFramework() instead of 6-framework inline check. Removed hardcoded framework.supported from config templates — only detected frameworks appear. checkI18nDependencies() unified across 4 modules (8→29 entries). 12 production files updated — hardcoded 7-language arrays expanded to 23.",
"PATCH: CLI language selector now derives display names and options from SettingsManager.getAvailableLanguages(), including the fallback manage/index.js entrypoint.",
"PATCH: Language selection prompts now render their numeric range dynamically from the installed UI locale count, preventing stale bounds during future locale expansion."
],
"breakingChanges": [],
"nextVersion": "5.0.1",
"supportedNodeVersions": ">=16.0.0",
"supportedFrameworks": {
"react-i18next": ">=11.0.0",
"vue-i18n": ">=9.0.0",
"angular-i18n": ">=12.0.0",
"next-i18next": ">=13.0.0",
"next-intl": ">=3.0.0",
"nuxt-i18n": ">=8.0.0",
"svelte-i18n": ">=3.0.0",
"sveltekit-i18n": ">=2.0.0",
"astro-i18next": ">=0.1.0",
"remix-i18next": ">=14.0.0",
"gatsby-plugin-react-i18next": ">=5.0.0",
"qwik-speak": ">=0.11.0",
"react-native-localize": ">=2.0.0",
"expo-localization": ">=14.0.0",
"ionic-angular": ">=6.0.0",
"ember-intl": ">=5.0.0",
"formatjs": ">=2.0.0",
"i18next": ">=21.0.0",
"django": ">=3.0.0",
"flask-babel": ">=2.0.0",
"fastapi": ">=0.70.0",
"spring-boot": ">=2.5.0",
"laravel": ">=8.0.0",
"fluent-rs": ">=0.16.0",
"gettext-rs": ">=0.7.0"
},
"supportPolicy": "Versions earlier than 5.0.0 use different licensing or may lack current reliability controls. Upgrade to 5.0.0 or newer.",
"deprecations": [
"4.3.0",
"4.3.1",
"4.3.2",
"4.3.3",
"4.7.2"
],
"deprecationMessage": "i18ntk 4.3.x and earlier have known security vulnerabilities (path traversal, JSON DoS). i18ntk 4.7.2 has a missing-module bug. Upgrade to i18ntk@5.0.0 or newer: npm install -g i18ntk@latest",
"securityAdvisories": [
"GHSA-i18ntk-4.3.x-path-traversal: Backup command accepted arbitrary paths without validation (fixed in 4.4.1)",
"GHSA-i18ntk-4.3.x-json-dos: Deeply nested JSON files could cause denial of service (fixed in 4.4.1)"
]
},
"readme": "# i18ntk v5.0.0\n\nFind, validate, and maintain application translations without adding runtime dependencies.\n\n\n\n[](https://www.npmjs.com/package/i18ntk)\n[](https://www.npmjs.com/package/i18ntk)\n[](https://nodejs.org)\n[](https://www.npmjs.com/package/i18ntk)\n[](LICENSE)\n[](https://socket.dev/npm/package/i18ntk/overview/5.0.0)\n\n[](https://marketplace.visualstudio.com/items?itemName=VladNoskov.i18ntk-workbench)\n[](https://marketplace.visualstudio.com/items?itemName=VladNoskov.i18ntk-lens)\n\n## Why i18ntk\n\n- Finds missing and unused keys across your source code and locale files.\n- Checks placeholders, tags, source-language leftovers, and other translation-quality issues.\n- Completes missing keys and translates only the entries that need attention.\n- Supports JavaScript, TypeScript, Python, PHP, Ruby, Go, Rust, JVM templates, and 30+ framework or i18n integrations.\n- Works interactively on your machine or non-interactively in automation, with no production dependencies.\n\nUse the CLI on its own, or pair it with [i18ntk Workbench](https://marketplace.visualstudio.com/items?itemName=VladNoskov.i18ntk-workbench) for project-wide management and [i18ntk Lens](https://marketplace.visualstudio.com/items?itemName=VladNoskov.i18ntk-lens) for inline editor feedback.\n\n## Quick start\n\nTry it without installing:\n\n```bash\nnpx i18ntk\n```\n\nOr install it for your project (required if using i18ntk/runtime):\n\n```bash\nnpm install --save-dev i18ntk\nnpx i18ntk --command=init\n```\n\nThen inspect translation health before making changes:\n\n```bash\nnpx i18ntk --command=analyze\nnpx i18ntk --command=validate\nnpx i18ntk --command=usage\n```\n\nUse `npx i18ntk` for the guided menu. It detects the project framework and adds only compatible source types and safe generated-file exclusions to a newly created configuration. For a walkthrough, see [Getting started](./docs/getting-started.md).\n\n## What's new in 5.0.0\n\n- **Stronger quality checks** for placeholders, tags, corrupted text, source-language leftovers, and unsafe bidirectional characters.\n- **Better framework detection** for Laravel, Spring Boot, Nuxt, next-intl, and mixed-stack projects.\n- **Faster repeat scans** and more reliable discovery across regional, namespaced, and underscore-style locale folders.\n- **Safer Auto Translate** that respects protected terms and reports unresolved work clearly.\n- **An optional LLM skill** for Codex, Claude Code, GitHub Copilot, and compatible agents.\n\nSee the [release notes](./CHANGELOG.md) for the full list of user-facing changes.\n\nUpgrading from v4? Follow the [v4 to v5 migration guide](./docs/migration-v4-to-v5.md), including the licensing change and one-time configuration migration.\n\n## Everyday workflows\n\n```bash\ni18ntk # guided menu\ni18ntk --command=analyze # translation coverage\ni18ntk --command=validate # quality checks\ni18ntk --command=usage # missing and unused keys\ni18ntk --command=complete # add missing keys\ni18ntk --command=translate # translate eligible entries\ni18ntk --command=report --format=json # shareable report\n```\n\nUse `npx i18ntk --command=<name>` when i18ntk is installed locally.\n\n## Command Reference\n\n| Command | Use it when you want to |\n| --- | --- |\n| `i18ntk` | Open the guided setup and maintenance menu. |\n| `init` | Create or extend a project configuration. |\n| `analyze`, `validate`, `usage` | Review coverage, translation quality, and key usage. |\n| `complete`, `translate` | Add missing entries or translate eligible values. |\n| `report`, `summary`, `sizing` | Produce a shareable status or planning view. |\n| `scanner`, `fixer`, `backup` | Find hardcoded text, repair locale data, or protect a snapshot. |\n| `skills` | Install i18ntk guidance for an AI coding agent. |\n\nEach command is also available as a standalone `i18ntk-<name>` executable.\n\n## Common Options\n\n```\n--code-dir <path> Source code directory\n--locales-dir <path> Locale files directory\n--output-dir <path> Report output directory\n--source-locale <code> Source language code (e.g. en)\n--framework <name> Override framework detection\n--no-prompt Skip interactive prompts\n--help Show help\n```\n\n## Auto Translate\n\n```bash\ni18ntk-translate locales/en/common.json de\ni18ntk-translate locales/en/common.json fr --dry-run --preserve-placeholders\n```\n\n**Providers:** Google (default), DeepL, LibreTranslate\n\n```bash\n# POSIX\nDEEPL_API_KEY=\"your-key\" i18ntk-translate locales/en/common.json de --provider deepl --no-confirm\n\n# PowerShell\n$env:DEEPL_API_KEY = \"your-key\"\ni18ntk-translate locales/en/common.json de --provider deepl --no-confirm\n```\n\n**Placeholder-aware translation** recognises `{name}`, `{{count}}`, `%s`, `:id`, `${value}`, `$t(key)`, and ICU patterns. By default, existing translations are left unchanged.\n\nProtected terms and keys via `i18ntk-auto-translate.json`:\n\n```json\n{\n \"version\": 1,\n \"terms\": [\"BrandName\", \"PRODUCT_CODE\"],\n \"keys\": [\"app.brandName\", \"product.*.symbol\"],\n \"values\": [\"BrandName Ltd\"],\n \"patterns\": [\"[A-Z]{2,}-\\\\d+\"]\n}\n```\n\n[Auto Translate guide →](./docs/auto-translate.md)\n\n## Configure your project\n\nExample `.i18ntk-config`:\n\n```json\n{\n \"version\": \"5.0.0\",\n \"sourceDir\": \"./src\",\n \"i18nDir\": \"./locales\",\n \"sourceLanguage\": \"en\",\n \"defaultLanguages\": [\"en\", \"de\", \"es\", \"fr\", \"ru\"],\n \"keyStyle\": \"dot.notation\",\n \"englishContentThresholdPercent\": 10,\n \"allowedEnglishTerms\": [\"BrandName\"],\n \"autoTranslate\": {\n \"placeholderMode\": \"preserve\",\n \"concurrency\": 12,\n \"onlyMissingOrEnglish\": true\n }\n}\n```\n\n[Configuration reference →](./docs/api/CONFIGURATION.md)\n\nWhen i18ntk detects a supported framework, it checks whether your setup version and configuration need a v5 update. The interactive menu asks before adding safe defaults for source file types, generated directories, scan caching, report summaries, and performance tracking. Your existing choices are preserved. See [framework configuration templates](./docs/framework-templates.md).\n\n## Find hardcoded text\n\nScan source files for text that should move into locale files. i18ntk understands common patterns across React, Vue, Angular, Svelte, Astro, Django, Flask, Python, Rust, Go, and more.\n\n```bash\ni18ntk-scanner --code-dir ./src --source-locale de\ni18ntk-scanner --code-dir ./src --source-locale ja --output-report\n```\n\n## Find unused and missing keys\n\nTrace key references, find likely unused entries, and recognise common dynamic patterns such as templates, arrays, and object maps.\n\n```bash\ni18ntk-usage --code-dir ./src --locales-dir ./locales --cleanup --dry-run-delete\n```\n\n## Runtime\n\n```js\nconst runtime = require('i18ntk/runtime');\nconst i18n = runtime.initRuntime({\n baseDir: './locales',\n language: 'en',\n fallbackLanguage: 'en',\n});\n\nconsole.log(i18n.t('common.hello'));\ni18n.setLanguage('fr');\nconsole.log(i18n.getAvailableLanguages());\n```\n\n**Lazy loading** reduces memory on large locale folders:\n\n```js\nconst i18n = runtime.initRuntime({ baseDir: './locales', language: 'en', lazy: true });\n```\n\n**Per-call language overrides:**\n\n```js\ni18n.t('common.hello', {}, { language: 'de' });\n```\n\n**Batch translation:**\n\n```js\ni18n.translateBatch(['menu.home', 'menu.settings']);\n```\n\nProduction guidance:\n\n- Use the instance from `initRuntime()` — not module-level `runtime.t()` — in multi-tenant apps\n- Use `lazy: true` for large folders; `preload: true` for small sets\n- Call `refresh(language)` after deploying changed locale files\n- `i18ntk/runtime/enhanced` remains available for async/encryption compatibility\n\n[Runtime guide →](./docs/runtime.md)\n\n## Watch\n\n```js\nconst watchLocales = require('i18ntk/utils/watch-locales');\nconst watcher = watchLocales('./locales');\n\nwatcher.on('change', (filePath) => console.log('changed:', filePath));\nwatcher.on('add', (filePath) => console.log('added:', filePath));\nwatcher.stop();\n```\n\nFeatures: 300ms debounce, SHA-256 hash tracking, 50-directory cap. The callback form `watchLocales('./locales', onChange)` is still supported.\n\n## Documentation\n\n- [Upgrade from v4 to v5](./docs/migration-v4-to-v5.md)\n- [Getting Started](./docs/getting-started.md)\n- [Configuration](./docs/api/CONFIGURATION.md)\n- [API Reference](./docs/api/API_REFERENCE.md)\n- [Runtime API](./docs/runtime.md)\n- [Auto Translate](./docs/auto-translate.md)\n- [Scanner Guide](./docs/scanner-guide.md)\n- [Environment Variables](./docs/environment-variables.md)\n\n## Use i18ntk with an AI coding agent\n\nGive your coding agent the same up-to-date i18ntk guidance you use. The installer finds supported skill locations and lets you choose where to add it:\n\n```bash\nnpx i18ntk --command=skills\nnpx i18ntk --command=skills --agents=codex,claude,copilot --scope=personal --dry-run --no-prompt\n```\n\nThe installer supports Codex, Claude Code, GitHub Copilot, shared Agent Skills, and compatible project folders. The core instructions are model-neutral; Codex receives optional OpenAI UI metadata, while Claude and Copilot receive the same portable workflow. The installer shows destinations and asks before changing anything. Existing skills are kept unless you choose to update them.\n\nFor manual installation, copy the complete `skills/i18ntk` folder into your agent's skills directory.\n\n## Security\n\n- No API key required for default Auto Translate\n- Do not store secrets in locale files, `.i18ntk-config`, or protection files\n- Report issues via [SECURITY.md](./SECURITY.md)\n\n## Related\n\n| Tool | Purpose |\n| ---------------- | ------------------------------------------- |\n| i18ntk Workbench | VS Code localization health dashboard |\n| i18ntk Lens | Inline hovers, CodeLens, and diagnostics |\n| PublishGuard | Pre-publish safety scanner for npm packages |\n| ContextKit | AI coding context manager |\n\n## License\n\ni18ntk 5.0.0 and later is source-available under a dual-license model:\n\n- **Personal and qualifying noncommercial use:** free under the [PolyForm Noncommercial License 1.0.0](./LICENSE).\n- **Business and commercial use:** requires a separate paid commercial license. This includes internal company tooling, CI/CD, consulting or client work, and use connected to a commercial product or service.\n\nCommercial customers can also request custom integration support for frameworks, monorepos, CI/CD pipelines, migrations, translation providers, and organization-specific workflows. Scope and support terms are agreed separately.\n\nLicensed public sites can use `i18ntk-license` to generate a searchable verification meta tag and `/i18ntk-license.json`. The tool does not phone home or collect visitor data; verification uses only intentionally published markers and licensing records.\n\nDownloading from npm does not grant commercial-use rights. See [Commercial licensing](./COMMERCIAL-LICENSE.md) for examples and how to request a license. For the technical upgrade and privacy-safe public marker workflow, see the [v4 to v5 migration guide](./docs/migration-v4-to-v5.md).\n\nEarlier versions released under MIT remain available under their original license terms.\n"
}