{"id":44815996,"url":"https://github.com/allenstu6311/vite-plugin-i18n-checker","last_synced_at":"2026-02-16T18:02:03.701Z","repository":{"id":307704765,"uuid":"1027235167","full_name":"allenstu6311/vite-plugin-i18n-checker","owner":"allenstu6311","description":"This is a Vite plugin for checking multi-language files in projects, ensuring key completeness and consistency across different language versions. It supports multiple file formats and flexible directory structures, helping developers maintain i18n translation file quality.","archived":false,"fork":false,"pushed_at":"2026-02-11T16:07:40.000Z","size":1087,"stargazers_count":8,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-02-12T00:52:36.077Z","etag":null,"topics":["check-keys","i18n","localization","plugin","vite"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/vite-plugin-i18n-checker","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/allenstu6311.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-27T15:47:41.000Z","updated_at":"2025-11-02T07:33:58.000Z","dependencies_parsed_at":"2025-08-28T18:12:20.971Z","dependency_job_id":"9e0e6109-0a0b-445c-9a80-4e5f750997f2","html_url":"https://github.com/allenstu6311/vite-plugin-i18n-checker","commit_stats":null,"previous_names":["allenstu6311/vite-plugin-i18n-checker"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/allenstu6311/vite-plugin-i18n-checker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allenstu6311%2Fvite-plugin-i18n-checker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allenstu6311%2Fvite-plugin-i18n-checker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allenstu6311%2Fvite-plugin-i18n-checker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allenstu6311%2Fvite-plugin-i18n-checker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/allenstu6311","download_url":"https://codeload.github.com/allenstu6311/vite-plugin-i18n-checker/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allenstu6311%2Fvite-plugin-i18n-checker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29514593,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-16T17:46:34.542Z","status":"ssl_error","status_checked_at":"2026-02-16T17:46:30.907Z","response_time":115,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["check-keys","i18n","localization","plugin","vite"],"created_at":"2026-02-16T18:02:03.170Z","updated_at":"2026-02-16T18:02:03.694Z","avatar_url":"https://github.com/allenstu6311.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# vite-plugin-i18n-checker\n\n[![npm version](https://img.shields.io/npm/v/vite-plugin-i18n-checker.svg)](https://www.npmjs.com/package/vite-plugin-i18n-checker)\n[![npm version](https://img.shields.io/npm/dt/vite-plugin-i18n-checker.svg)](https://www.npmjs.com/package/vite-plugin-i18n-checker)\n[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)\n\n[English](README.md) | [中文](README.zh-CN.md)\n\n## 📖 Project Introduction\n\nThis is a **Vite plugin** for checking multi-language files in projects, ensuring key completeness and consistency across different language versions. It supports multiple file formats and flexible directory structures, helping developers maintain i18n translation file quality.\n\n### ✨ Key Features\n\n- 🔍 **Automatic Checking** - Automatically compares key structures across language files\n- 📁 **Multi-format Support** - Supports `.json`, `.yml`, `yaml`, `.ts`, `.js` formats\n- 🏗️ **Flexible Structure** - Supports both single-file and multi-file directory structures\n- ⚡ **Flexible Execution Mode** - Choose to run during development or build\n- 📊 **HTML Reports** - Generate beautiful HTML reports with two-level collapsible structure and automatic pagination\n- 📈 **Report History** - Save historical reports by timestamp with configurable auto-cleanup strategy\n- 🚫 **File \u0026 Key Filtering** - Support include/exclude patterns for filtering files and keys\n- ⚙️ **Custom Rules** - Define custom validation rules for advanced use cases\n- 🛠️ **CLI Tool** - Supports command-line tool for CI environments\n\n### 🎯 Check Types\n\n- **Missing Keys** - Missing translation keys\n- **Extra Keys** - Redundant translation keys\n- **Invalid Keys** - Keys with mismatched structure types (data type mismatch, array length mismatch)\n- **Missing Files** - Missing language files\n- **Empty Files** - Empty language files\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Usage](#usage)\n  - [Vite Plugin](#vite-plugin)\n  - [CLI Tool](#cli-tool)\n- [Configuration](#configuration)\n- [HTML Reports](#html-reports)\n- [Supported File Structures](#supported-file-structures)\n  - [Single File Mode](#single-file-mode)\n  - [Multi-file Mode](#multi-file-mode)\n- [CI Integration](#ci-integration)\n  - [GitHub Actions](#github-actions)\n- [Advanced Usage](#advanced-usage)\n  - [Custom Rules](#custom-rules)\n  - [File Filtering](#file-filtering)\n- [Examples](#examples)\n- [Development](#development)\n- [Links](#links)\n\n## Installation\n\n```bash\nnpm install -D vite-plugin-i18n-checker\n# or\nyarn add -D vite-plugin-i18n-checker\n# or\npnpm add -D vite-plugin-i18n-checker\n```\n\n## Usage\n\n### Vite Plugin\n\nConfigure in `vite.config.ts`:\n\n```typescript\nimport { defineConfig } from 'vite'\nimport i18nChecker from 'vite-plugin-i18n-checker'\n\nexport default defineConfig({\n  plugins: [\n    i18nChecker({\n      sourceLocale: 'zh_CN',        // Base language code\n      localesPath: './src/locales', // Language files directory\n      extensions: 'json',           // File extension\n      failOnError: false,           // Whether to interrupt on error (optional)\n      report: {                     // Report configuration (optional)\n        dir: 'i18CheckerReport',    // Report output directory\n        retention: 7                // Report retention days\n      }\n    })\n  ]\n})\n```\n\n### CLI Tool\n\n```bash\nnpx i18n-check -s zh_CN -p ./src/locales -x json\n```\n\n#### CLI Options\n\n**`--sourceLocale, -s`** (Required)\nDefine base language code, all target files will be compared against this language.\n\n```bash\nnpx i18n-check -s zh_CN -p ./src/locales -x json\n```\n\n**`--localesPath, -p`** (Required)\nDefine language files directory path.\n\n```bash\nnpx i18n-check -s zh_CN -p ./src/locales -x json\n```\n\n**`--extensions, -x`** (Required)\nDefine file extensions to check.\n\n```bash\nnpx i18n-check -s zh_CN -p ./src/locales -x json\n```\n\n**`--failOnError, -f`**\nWhether to interrupt execution when errors are found.\n\n```bash\nnpx i18n-check -s zh_CN -p ./src/locales -x json -f\n```\n\n**`--applyMode, -m`**\nSet execution mode (serve/build/all).\n\n```bash\nnpx i18n-check -s zh_CN -p ./src/locales -x json -m build\n```\n\n**`--include`**\nInclude specific file patterns (supports multiple patterns).\n\n```bash\nnpx i18n-check -s zh_CN -p ./src/locales -x json --include \"**/common/**\"\n```\n\n**`--exclude, -e`**\nIgnore specific file patterns (supports multiple patterns).\n\n```bash\nnpx i18n-check -s zh_CN -p ./src/locales -x json -e \"**/test/**\" \"**/*.spec.*\"\n```\n\n**`--ignoreKeys, -i`**\nIgnore specific key patterns (supports multiple patterns).\n\n```bash\nnpx i18n-check -s zh_CN -p ./src/locales -x json -i \"common.debug\" \"unused.*\"\n```\n\n**`--rules, -r`**\nCustom validation rules file path (JavaScript/TypeScript file).\n\n```bash\nnpx i18n-check -s zh_CN -p ./src/locales -x json -r \"./custom-rules.mjs\"\n```\n\nRules file format example:\n\n```javascript\n// custom-rules.mjs\nexport default [\n  {\n    abnormalType: 'forbiddenKey',\n    check: ({ source, target, key, pathStack }) =\u003e key === 'theme',\n    msg: 'Theme key is not allowed in translations'\n  },\n  {\n    abnormalType: 'emptyValue',\n    check: ({ source, target, key, pathStack }) =\u003e target[key] === '',\n    msg: 'Translation values cannot be empty'\n  }\n];\n```\n\n**`--report-dir \u003cpath\u003e`**\nSet report output directory.\n\n```bash\nnpx i18n-check -s zh_CN -p ./src/locales -x json --report-dir checkReport\n```\n\n**`--report-retention \u003cdays\u003e`**\nSet report retention days (auto-cleanup expired reports).\n\n```bash\nnpx i18n-check -s zh_CN -p ./src/locales -x json --report-retention 7\n```\n\n**`-w, --watch`**\nWatch file changes and automatically re-check when files are modified.\n\n```bash\nnpx i18n-check -s zh_CN -p ./src/locales -x json -w\n```\n\n## Configuration\n\n| Parameter | Type | Default | Required | Description |\n|-----------|------|---------|----------|-------------|\n| `sourceLocale` | `string` | - | ✅ | Base language code (e.g., `zh_CN`) |\n| `localesPath` | `string` | - | ✅ | Root directory path for language files |\n| `extensions` | `SupportedParserType` | `'json'` | ✅ | Supported file extensions (`json`, `ts`, `js`, `yml`, `yaml`) |\n| `failOnError` | `boolean` | `false` | ❌ | Whether to interrupt on error |\n| `applyMode` | `'serve' \\| 'build' \\| 'all'` | `'serve'` | ❌ | Plugin execution mode (development/build/all) |\n| `include` | `(string \\| RegExp)[]` | `[]` | ❌ | File patterns to include |\n| `exclude` | `(string \\| RegExp)[]` | `[]` | ❌ | File patterns to ignore |\n| `ignoreKeys` | `(string \\| RegExp)[]` | `[]` | ❌ | Key patterns to ignore |\n| `rules` | `CustomRule[]` | `[]` | ❌ | Custom validation rules |\n| `watch` | `boolean` | `false` | ❌ | Whether to watch file changes |\n| `report` | `ReportOptions` | `{ dir: 'i18CheckerReport', retention: 7 }` | ❌ | Report configuration |\n\n### ReportOptions\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `dir` | `string` | `'i18CheckerReport'` | Report output directory |\n| `retention` | `number` | `7` | Report retention days (auto-cleanup) |\n\n### CustomRule\n\n```typescript\ntype CustomRule = {\n  abnormalType: string;                     // Custom anomaly type name\n  check: (ctx: CollectAbnormalKeysParam) =\u003e boolean;  // Check function\n  msg?: string;                            // Error message (optional)\n}\n\n// Check function parameters\ntype CollectAbnormalKeysParam = {\n  source: any;        // Source language object\n  target: any;        // Target language object\n  key: string;        // Current key being checked\n  pathStack: string[]; // Array of keys representing the current path\n}\n```\n\n## HTML Reports\n\nThe plugin automatically generates beautiful HTML reports for better visualization.\n\n### Report Features\n\n- 📋 **Two-level Collapsible Structure** - First level by anomaly type, second level by file grouping\n- 📄 **Automatic Pagination** - Automatically paginate when a single file has more than 20 issues\n- 🎨 **Beautiful Styling** - GitHub + Playwright mixed design style\n- 🕐 **Historical Records** - Save each check result by timestamp\n- 🗑️ **Auto-cleanup** - Automatically clean up expired reports based on `retention` configuration\n\n### Report Directory Structure\n\n```\ni18CheckerReport/           # Report root directory (configurable)\n└── 2026-02-15/            # Grouped by date\n    ├── 09-30-00/          # Timestamp directory\n    │   └── index.html\n    ├── 10-15-30/\n    │   └── index.html\n    └── 14-20-45/\n        └── index.html\n```\n\n### Configuration Example\n\n```typescript\ni18nChecker({\n  sourceLocale: 'zh_CN',\n  localesPath: './src/locales',\n  extensions: 'json',\n  report: {\n    dir: 'checkReport',    // Custom report directory\n    retention: 30          // Keep reports for 30 days\n  }\n})\n```\n\n## Supported File Structures\n\n### Single File Mode\n\n```\nsrc/locales/\n├── zh_CN.json    # Base language file\n├── en_US.json    # Other language files\n└── es_ES.json\n```\n\n### Multi-file Mode\n\n```\nsrc/locales/\n├── zh_CN/        # Base language directory\n│   ├── common.ts\n│   ├── login.ts\n│   └── table/\n│       └── table.ts\n├── en_US/        # Other language directories\n│   ├── common.ts\n│   ├── login.ts\n│   └── table/\n│       └── table.ts\n└── es_ES/\n    ├── common.ts\n    ├── login.ts\n    └── table/\n        └── table.ts\n```\n\n## CI Integration\n\n### GitHub Actions\n\nCreate workflow in `.github/workflows/i18n-check.yml`:\n\n```yaml\nname: i18n Check\n\non:\n  push:\n    branches: [ main, develop ]\n  pull_request:\n    branches: [ main ]\n\njobs:\n  i18n-check:\n    runs-on: ubuntu-latest\n\n    steps:\n    - uses: actions/checkout@v4\n\n    - name: Setup Node.js\n      uses: actions/setup-node@v4\n      with:\n        node-version: '18'\n        cache: 'npm'\n\n    - name: Install dependencies\n      run: npm ci\n\n    - name: Check i18n files\n      run: npx i18n-check --sourceLocale zh_CN --localesPath ./src/locales --extensions json\n```\n\n## Advanced Usage\n\n### Custom Rules\n\nThe `check` function receives a context object with the following properties:\n- `source`: Source language object\n- `target`: Target language object\n- `pathStack`: Array of keys representing the current path\n- `key`: Current key being checked\n\n```typescript\ni18nChecker({\n  sourceLocale: 'zh_CN',\n  localesPath: './src/locales',\n  extensions: 'json',\n  // Define custom validation rules\n  rules: [\n    {\n      abnormalType: 'forbiddenKey',\n      check: ({ source, target, pathStack, key }) =\u003e key === 'theme',\n      msg: 'Theme key is not allowed in translations'\n    },\n    {\n      abnormalType: 'emptyValue',\n      check: ({ source, target, pathStack, key }) =\u003e target[key] === '',\n      msg: 'Translation values cannot be empty'\n    },\n    {\n      abnormalType: 'nestedCheck',\n      check: ({ source, target, pathStack, key }) =\u003e {\n        // Check if nested object has specific structure\n        return pathStack.includes('user') \u0026\u0026 key === 'name' \u0026\u0026\n               typeof target[key] !== 'string'\n      },\n      msg: 'User name must be a string'\n    }\n  ]\n})\n```\n\n### File Filtering\n\n```typescript\ni18nChecker({\n  sourceLocale: 'zh_CN',\n  localesPath: './src/locales',\n  extensions: 'json',\n  // Only include specific files\n  include: [\n    '**/common/**',         // Only check common directory\n    '**/auth/**'            // Only check auth directory\n  ],\n  // Ignore specific files\n  exclude: [\n    '**/test/**',           // Ignore all files in test directories\n    /\\.spec\\./,             // Ignore files with .spec. in name\n    'temp.json'             // Ignore specific file\n  ],\n  // Ignore specific keys\n  ignoreKeys: [\n    'common.debug',         // Ignore debug keys\n    'unused'                // Ignore specific key\n  ]\n})\n```\n\n## Examples\n\n### Basic Configuration\n\n```typescript\ni18nChecker({\n  sourceLocale: 'zh_CN',\n  localesPath: './src/locales',\n  extensions: 'ts',\n  failOnError: false,      // Don't interrupt development flow, only show warnings\n})\n```\n\n### Setting Execution Mode\n\n```typescript\n// Only run in development mode (default)\ni18nChecker({\n  sourceLocale: 'zh_CN',\n  localesPath: './src/locales',\n  extensions: 'json',\n  applyMode: 'serve',      // Only run in development server\n})\n\n// Only run in build mode\ni18nChecker({\n  sourceLocale: 'zh_CN',\n  localesPath: './src/locales',\n  extensions: 'json',\n  applyMode: 'build',      // Only run during build\n})\n\n// Run in both build and development mode\ni18nChecker({\n  sourceLocale: 'zh_CN',\n  localesPath: './src/locales',\n  extensions: 'json',\n  applyMode: 'all',\n})\n```\n\n### Watch File Changes\n\n```typescript\n// Enable watch mode - automatically re-check when files change\ni18nChecker({\n  sourceLocale: 'zh_CN',\n  localesPath: './src/locales',\n  extensions: 'json',\n  watch: true,      // Automatically check when translation files are modified\n})\n\n// Disable watch mode - only check once during startup (default)\ni18nChecker({\n  sourceLocale: 'zh_CN',\n  localesPath: './src/locales',\n  extensions: 'json',\n  watch: false,     // Disable automatic re-checking\n})\n```\n\n### Multiple File Format Mixing\n\n```typescript\n// Check JSON files\ni18nChecker({\n  sourceLocale: 'zh_CN',\n  localesPath: './src/locales/json',\n  extensions: 'json',\n})\n\n// Check TypeScript files\ni18nChecker({\n  sourceLocale: 'zh_CN',\n  localesPath: './src/locales/ts',\n  extensions: 'ts',\n})\n```\n\n### Complete Configuration Example\n\n```typescript\ni18nChecker({\n  sourceLocale: 'zh_CN',\n  localesPath: './src/locales',\n  extensions: 'json',\n  failOnError: true,\n  applyMode: 'all',\n  watch: true,\n  include: ['**/common/**', '**/auth/**'],\n  exclude: ['**/test/**', /\\.spec\\./],\n  ignoreKeys: ['debug.*', 'temp'],\n  report: {\n    dir: 'i18n-reports',\n    retention: 30\n  },\n  rules: [\n    {\n      abnormalType: 'emptyValue',\n      check: ({ target, key }) =\u003e target[key] === '',\n      msg: 'Translation values cannot be empty'\n    }\n  ]\n})\n```\n\n## 📝 Supported File Formats\n\n### JSON Format\n```json\n{\n  \"common\": {\n    \"save\": \"Save\",\n    \"cancel\": \"Cancel\"\n  },\n  \"login\": {\n    \"title\": \"Login\"\n  }\n}\n```\n\n### TypeScript/JavaScript Format\n```typescript\nexport default {\n  common: {\n    save: 'Save',\n    cancel: 'Cancel'\n  },\n  login: {\n    title: 'Login'\n  }\n}\n```\n\n### YAML Format\n```yaml\ncommon:\n  save: Save\n  cancel: Cancel\nlogin:\n  title: Login\n```\n\n## 📊 Error Report Examples\n\n### CLI Report\n\n```\nMissing keys\n╔══════════════════════════════════════╤═══════════════════════╤═══════════════════════╗\n║ file                                 │ key                   │ remark                ║\n╠══════════════════════════════════════╪═══════════════════════╪═══════════════════════╣\n║ src/locales/en_US.json               │ common.delete         │                       ║\n║ src/locales/en_US.json               │ login.password        │                       ║\n╚══════════════════════════════════════╧═══════════════════════╧═══════════════════════╝\n\nExtra keys\n╔══════════════════════════════════════╤═══════════════════════╤═══════════════════════╗\n║ file                                 │ key                   │ remark                ║\n╠══════════════════════════════════════╪═══════════════════════╪═══════════════════════╣\n║ src/locales/zh_CN.json               │ common.extra          │                       ║\n╚══════════════════════════════════════╧═══════════════════════╧═══════════════════════╝\n```\n\n### HTML Report\n\nHTML reports provide better visual experience:\n- Collapsible panels grouped by anomaly type\n- Second-level collapsible grouping by file\n- Automatic pagination for more than 20 items\n- Support click to expand/collapse\n\nAfter checking is complete, the report will be output to the configured directory, and the terminal will display the report path:\n```\nPlease check the detailed report at \"/path/to/your/project/i18CheckerReport\"\n```\n\n## Development\n\n### Project Structure\n\n```\nsrc/\n├── abnormal/          # Anomaly detection and processing\n├── bin/               # CLI entry point\n├── checker/           # File comparison logic\n├── config/            # Configuration management\n├── errorHandling/     # Error handling and messages\n├── helpers/           # Helper functions\n├── parser/            # File parsers\n├── report/            # Report generation\n│   └── abnormalKey/   # Abnormal key reports\n│       ├── cli-renderer.ts   # CLI report rendering\n│       ├── html-renderer.ts  # HTML report rendering\n│       ├── index.ts          # Report coordinator\n│       └── types.ts          # Report type definitions\n└── utils/             # Utility functions\n```\n\n### Local Development\n\n```bash\n# Install dependencies\npnpm install\n\n# Run tests\npnpm test\n\n# Build\npnpm build\n\n# Development mode\npnpm dev\n\n# Lint code\npnpm lint\n```\n\n## Links\n\n- [GitHub Repository](https://github.com/allenstu6311/vite-plugin-i18n-checker)\n- [NPM Package](https://www.npmjs.com/package/vite-plugin-i18n-checker)\n- [Issues](https://github.com/allenstu6311/vite-plugin-i18n-checker/issues)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fallenstu6311%2Fvite-plugin-i18n-checker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fallenstu6311%2Fvite-plugin-i18n-checker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fallenstu6311%2Fvite-plugin-i18n-checker/lists"}