{"id":29283820,"url":"https://github.com/mariokreitz/i18n-excel-manager","last_synced_at":"2026-01-20T04:01:11.442Z","repository":{"id":299409914,"uuid":"1002937151","full_name":"mariokreitz/i18n-excel-manager","owner":"mariokreitz","description":"CLI tool for converting and validating i18n JSON and Excel files with placeholder validation","archived":false,"fork":false,"pushed_at":"2025-12-15T21:31:26.000Z","size":1546,"stargazers_count":5,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-19T05:40:09.306Z","etag":null,"topics":["cli","converter","excel","i18n","internationalization","json","l10n","language","localization-tool","translations"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/i18n-excel-manager","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mariokreitz.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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-06-16T11:24:12.000Z","updated_at":"2025-12-15T21:31:22.000Z","dependencies_parsed_at":"2025-10-28T08:13:04.443Z","dependency_job_id":"c41895ca-39eb-4b68-9c12-20a2d2db763f","html_url":"https://github.com/mariokreitz/i18n-excel-manager","commit_stats":null,"previous_names":["mariokreitz/i18n-to-excel"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/mariokreitz/i18n-excel-manager","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mariokreitz%2Fi18n-excel-manager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mariokreitz%2Fi18n-excel-manager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mariokreitz%2Fi18n-excel-manager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mariokreitz%2Fi18n-excel-manager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mariokreitz","download_url":"https://codeload.github.com/mariokreitz/i18n-excel-manager/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mariokreitz%2Fi18n-excel-manager/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28595314,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T02:08:49.799Z","status":"ssl_error","status_checked_at":"2026-01-20T02:08:44.148Z","response_time":117,"last_error":"SSL_read: 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":["cli","converter","excel","i18n","internationalization","json","l10n","language","localization-tool","translations"],"created_at":"2025-07-05T20:15:14.364Z","updated_at":"2026-01-20T04:01:11.386Z","avatar_url":"https://github.com/mariokreitz.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# i18n-excel-manager\n\n[![CI](https://github.com/mariokreitz/i18n-excel-manager/actions/workflows/ci.yml/badge.svg)](https://github.com/mariokreitz/i18n-excel-manager/actions/workflows/ci.yml)\n[![npm version](https://img.shields.io/npm/v/i18n-excel-manager.svg?style=flat)](https://www.npmjs.com/package/i18n-excel-manager)\n[![npm downloads](https://img.shields.io/npm/dm/i18n-excel-manager.svg?style=flat)](https://www.npmjs.com/package/i18n-excel-manager)\n[![codecov](https://codecov.io/gh/mariokreitz/i18n-excel-manager/branch/main/graph/badge.svg)](https://codecov.io/gh/mariokreitz/i18n-excel-manager)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/logo.png\" alt=\"i18n-excel-manager logo\" width=\"320\" /\u003e\n\u003c/p\u003e\n\n\u003ch2 align=\"center\"\u003ei18n-excel-manager\u003c/h2\u003e\n\u003cp align=\"center\"\u003e\u003cb\u003eEffortless conversion between i18n JSON files and Excel for Angular and modern web projects.\u003c/b\u003e\u003c/p\u003e\n\n---\n\n## ✨ Features\n\n### Core Conversion\n\n- **Bidirectional Conversion**: Convert i18n JSON files to Excel and vice versa.\n- **Nested Key Support**: Handles deeply nested translation structures with dot-notation flattening.\n- **Language Mapping**: Use full language names in Excel headers (e.g., \"German\" instead of \"de\").\n- **Placeholder Validation**: Detect inconsistent placeholders (e.g., `{{value}}`) across languages.\n- **Duplicate Detection**: Identify and handle duplicate translation keys.\n\n### Codebase Analysis\n\n- **Missing Key Detection**: Find translation keys used in code but missing from JSON files.\n- **Unused Key Detection**: Identify translation keys defined in JSON but never used in code.\n- **Flexible Patterns**: Scan any file types using customizable glob patterns.\n- **Multi-file Reports**: Get analysis reports for each language file separately.\n\n### AI-Powered Translation\n\n- **Gemini Integration**: Auto-translate missing values using Google's Gemini AI.\n- **Placeholder Preservation**: AI preserves `{{placeholders}}`, HTML tags, and formatting.\n- **Multiple Models**: Choose from `gemini-2.5-flash`, `gemini-1.5-flash`, or `gemini-1.5-pro`.\n- **Batch Processing**: Efficiently translates multiple strings in a single API call.\n\n### Developer Experience\n\n- **Interactive CLI**: User-friendly menu-driven interface for all operations.\n- **Dry-Run Mode**: Preview changes without writing files.\n- **Initialization**: Quickly scaffold i18n folders and starter JSON files.\n- **Path Safety**: Prevent directory traversal attacks with path validation.\n- **Node.js API**: Programmatic access for CI/CD integrations.\n\n---\n\n## 📑 Table of Contents\n\n- [Installation](#-installation)\n- [Quick Start](#-quick-start)\n- [Usage](#-usage)\n  - [Interactive Mode](#interactive-mode)\n  - [Initialize i18n Files](#initialize-i18n-files)\n  - [Convert JSON to Excel](#convert-json-to-excel)\n  - [Convert Excel to JSON](#convert-excel-to-json)\n  - [Analyze Codebase](#analyze-codebase)\n  - [AI Auto-Translation](#ai-auto-translation)\n- [API](#-api)\n- [Angular Integration](#-angular-integration)\n- [Configuration](#-configuration)\n- [CLI Options Reference](#-cli-options-reference)\n- [Migration Guide](#-migration-guide)\n- [Error Handling](#-error-handling)\n- [Architecture](#-architecture)\n- [Known Issues](#-known-issues)\n- [Development](#-development)\n- [Contributing](#-contributing)\n- [License](#-license)\n\n---\n\n## 📦 Installation\n\n### Requirements\n\n- Node.js \u003e= 20\n- Tested on Node.js 20.x, 22.x, and 24.x\n\n### Global Installation (Recommended)\n\n```bash\nnpm install -g i18n-excel-manager\n```\n\n### Local Installation (as dev dependency)\n\n```bash\nnpm install --save-dev i18n-excel-manager\n```\n\n---\n\n## 🚀 Quick Start\n\n1. **Install globally:**\n\n   ```bash\n   npm install -g i18n-excel-manager\n   ```\n\n2. **Initialize a new project** (creates `public/assets/i18n` with starter files):\n\n   ```bash\n   i18n-excel-manager init --output ./public/assets/i18n --languages en,de,fr\n   ```\n\n3. **Convert JSON to Excel:**\n\n   ```bash\n   i18n-excel-manager i18n-to-excel --input ./public/assets/i18n --output translations.xlsx\n   ```\n\n4. **Edit the Excel file** with your translations.\n\n5. **Convert back to JSON:**\n\n   ```bash\n   i18n-excel-manager excel-to-i18n --input translations.xlsx --output ./public/assets/i18n\n   ```\n\n6. **Analyze your codebase** for missing/unused keys:\n\n   ```bash\n   i18n-excel-manager analyze --input ./public/assets/i18n --pattern \"src/**/*.{ts,html}\"\n   ```\n\n7. **Auto-translate missing values** with AI:\n\n   ```bash\n   i18n-excel-manager analyze --translate --input translations.xlsx --api-key YOUR_GEMINI_KEY\n   ```\n\n\u003e **Tip:** Running `i18n-excel-manager` without arguments opens an interactive menu with all options.\n\n---\n\n## 🛠️ Usage\n\n### Interactive Mode\n\nRun without arguments for a guided experience:\n\n```bash\ni18n-excel-manager\n```\n\nThe interactive menu provides access to all features:\n\n- Convert i18n files to Excel\n- Convert Excel to i18n files\n- Analyze Codebase (Missing/Unused keys)\n- AI Auto-Translate (Fill missing translations)\n- Initialize i18n files\n\nIf the default i18n folder is missing or empty, the CLI will offer to initialize it.\n\n### Initialize i18n Files\n\nCreate the i18n directory and language files with minimal starter content. Existing files are never overwritten.\n\n```bash\ni18n-excel-manager init \\\n  --output ./public/assets/i18n \\\n  --languages en,de,fr\n```\n\n**Options:**\n\n- Use `--dry-run` to preview which files would be created.\n- Omit `--languages` to choose interactively from configured languages.\n\n**Example output:**\n\n```\n✔ Created: public/assets/i18n/en.json\n✔ Created: public/assets/i18n/de.json\n✔ Created: public/assets/i18n/fr.json\n```\n\n### Convert JSON to Excel\n\nConvert your i18n JSON files into an Excel workbook for easy editing and collaboration:\n\n```bash\ni18n-excel-manager i18n-to-excel \\\n  --input ./public/assets/i18n \\\n  --output translations.xlsx \\\n  --sheet-name \"Translations\"\n```\n\nThe Excel file will have:\n\n- Column A: Translation keys (dot-notation)\n- Subsequent columns: One per language (en, de, fr, etc.)\n\n### Convert Excel to JSON\n\nConvert an Excel workbook back to individual JSON files per language:\n\n```bash\ni18n-excel-manager excel-to-i18n \\\n  --input translations.xlsx \\\n  --output ./public/assets/i18n \\\n  --fail-on-duplicates\n```\n\n**Options:**\n\n- `--fail-on-duplicates`: Exit with error if duplicate keys are detected.\n- `--dry-run`: Preview changes without writing files.\n\n### Analyze Codebase\n\nScan your source code to find translation keys that are missing from your JSON files or defined but never used:\n\n```bash\ni18n-excel-manager analyze \\\n  --input ./public/assets/i18n \\\n  --pattern \"src/**/*.{ts,html}\"\n```\n\n**What it detects:**\n\n- **Missing keys**: Keys used in code (e.g., `{{ 'app.title' | translate }}`) but not defined in JSON.\n- **Unused keys**: Keys defined in JSON but never referenced in your codebase.\n\n**Supported patterns in code:**\n\n```typescript\n// Angular pipe syntax\n{\n    {\n        'KEY.NAME' | translate\n    }\n}\n\n// TranslateService methods\nthis.translate.get('KEY.NAME');\nthis.translate.instant('KEY.NAME');\nthis.translate.stream('KEY.NAME');\n\n// Directive syntax\n\u003cdiv translate = \"KEY.NAME\" \u003e \u003c/div\u003e\n\u003c div [translate] = \"'KEY.NAME'\" \u003e \u003c/div\u003e\n```\n\n**Example output:**\n\n```\nAnalysis Report:\nTotal Code Keys Found: 42\n\nen.json\n  Missing in JSON:\n    - app.newFeature\n    - errors.timeout\n  Unused in Code:\n    - legacy.oldButton\n\nde.json\n  All good!\n```\n\n### AI Auto-Translation\n\nAutomatically translate missing values in your Excel file using Google's Gemini AI:\n\n```bash\ni18n-excel-manager analyze \\\n  --translate \\\n  --input translations.xlsx \\\n  --api-key YOUR_GEMINI_API_KEY \\\n  --source-lang en \\\n  --model gemini-2.5-flash\n```\n\n**API Key Configuration:**\n\nThe API key can be provided in three ways (in order of precedence):\n\n1. CLI flag: `--api-key YOUR_KEY`\n2. Environment variable: `GEMINI_API_KEY`\n3. Fallback environment variable: `I18N_MANAGER_API_KEY`\n\n**Available Models:**\n\n| Model              | Description                  |\n| ------------------ | ---------------------------- |\n| `gemini-2.5-flash` | Fast and efficient (default) |\n| `gemini-1.5-flash` | Balanced speed and quality   |\n| `gemini-1.5-pro`   | Highest quality, slower      |\n\n**Features:**\n\n- Preserves placeholders like `{{value}}`, `{0}`, etc.\n- Maintains HTML tags and formatting\n- Processes translations in efficient batches\n- Uses low temperature (0.2) for consistent results\n\n**Interactive Mode:**\n\nWhen using interactive mode, you'll be prompted for:\n\n- Path to Excel file\n- Source language code\n- API key (can be masked input)\n- Model selection\n\n---\n\n## 📚 API\n\nUse the library programmatically in your Node.js applications:\n\n```javascript\nimport {\n  convertToExcel,\n  convertToJson,\n  analyze,\n  translate,\n} from 'i18n-excel-manager';\n```\n\n### convertToExcel(sourcePath, targetFile, options?)\n\nConvert JSON localization files to an Excel workbook.\n\n```javascript\nawait convertToExcel('./public/assets/i18n', 'translations.xlsx', {\n  sheetName: 'Translations',\n  dryRun: false,\n  languageMap: { en: 'English', de: 'Deutsch' },\n});\n```\n\n### convertToJson(sourceFile, targetPath, options?)\n\nConvert an Excel workbook to JSON localization files.\n\n```javascript\nawait convertToJson('translations.xlsx', './public/assets/i18n', {\n  sheetName: 'Translations',\n  failOnDuplicates: true,\n});\n```\n\n### analyze(options)\n\nAnalyze the codebase for missing and unused translation keys.\n\n```javascript\nconst report = await analyze({\n  sourcePath: './public/assets/i18n',\n  codePattern: 'src/**/*.{ts,html}',\n});\n\nconsole.log(`Total keys in code: ${report.totalCodeKeys}`);\n\nfor (const [file, result] of Object.entries(report.fileReports)) {\n  console.log(`${file}:`);\n  console.log(`  Missing: ${result.missing.join(', ')}`);\n  console.log(`  Unused: ${result.unused.join(', ')}`);\n}\n```\n\n**Return type:**\n\n```typescript\n{\n    totalCodeKeys: number;\n    fileReports: {\n        [ filename\n    :\n        string\n    ]:\n        {\n            missing: string[];  // Keys in code but not in JSON\n            unused: string[];   // Keys in JSON but not in code\n        }\n    }\n}\n```\n\n### translate(options)\n\nAuto-translate missing values in an Excel workbook using Gemini AI.\n\n```javascript\nawait translate({\n  input: './translations.xlsx',\n  apiKey: process.env.GEMINI_API_KEY,\n  sourceLang: 'en',\n  model: 'gemini-2.5-flash',\n  languageMap: { en: 'English', de: 'German', fr: 'French' },\n});\n```\n\n**Options:**\n\n| Option        | Type   | Required | Default              | Description                           |\n| ------------- | ------ | -------- | -------------------- | ------------------------------------- |\n| `input`       | string | Yes      | -                    | Path to the Excel file                |\n| `apiKey`      | string | Yes      | -                    | Gemini API key                        |\n| `sourceLang`  | string | No       | `'en'`               | Source language code                  |\n| `model`       | string | No       | `'gemini-2.5-flash'` | Gemini model to use                   |\n| `languageMap` | object | No       | `{}`                 | Language code to display name mapping |\n\n---\n\n## 🔧 Angular Integration\n\nThis tool is designed to work seamlessly with Angular's i18n workflow. It's compatible with **Angular 17+** and \\*\n\\*ngx-translate v17+\\*\\*.\n\n### Project Structure\n\nA typical Angular project structure for i18n:\n\n```\nmy-angular-app/\n├── public/\n│   └── assets/\n│       └── i18n/\n│           ├── en.json\n│           ├── de.json\n│           └── fr.json\n├── src/\n│   └── app/\n│       ├── app.component.ts\n│       └── app.config.ts\n└── angular.json\n```\n\n### Installation\n\nInstall ngx-translate packages:\n\n```bash\nnpm install @ngx-translate/core @ngx-translate/http-loader\n```\n\n### App Configuration (Angular 20+ / ngx-translate v17+)\n\nConfigure the translation service in `src/app/app.config.ts`:\n\n```typescript\nimport { ApplicationConfig } from '@angular/core';\nimport { provideHttpClient, withFetch } from '@angular/common/http';\nimport { provideTranslateService } from '@ngx-translate/core';\nimport { provideTranslateHttpLoader } from '@ngx-translate/http-loader';\n\nexport const appConfig: ApplicationConfig = {\n  providers: [\n    provideHttpClient(withFetch()),\n    provideTranslateService({\n      loader: provideTranslateHttpLoader({\n        prefix: './assets/i18n/',\n        suffix: '.json',\n      }),\n      fallbackLang: 'en',\n      lang: 'en',\n    }),\n  ],\n};\n```\n\n### Using Translations in Components\n\nUse the `TranslatePipe` and `TranslateService` in your standalone components:\n\n```typescript\nimport { Component, inject, signal } from '@angular/core';\nimport { TranslateService, TranslatePipe } from '@ngx-translate/core';\n\n@Component({\n  selector: 'app-root',\n  imports: [TranslatePipe],\n  template: `\n    \u003ch1\u003e{{ 'app.title' | translate }}\u003c/h1\u003e\n    \u003cp\u003e{{ 'app.welcome' | translate: { name: userName() } }}\u003c/p\u003e\n\n    \u003cbutton (click)=\"switchLanguage('en')\"\u003eEnglish\u003c/button\u003e\n    \u003cbutton (click)=\"switchLanguage('de')\"\u003eDeutsch\u003c/button\u003e\n  `,\n})\nexport class AppComponent {\n  private translate = inject(TranslateService);\n\n  userName = signal('User');\n\n  switchLanguage(lang: string) {\n    this.translate.use(lang);\n  }\n}\n```\n\n### Using the Translate Directive\n\nFor translating element content directly:\n\n```typescript\nimport { Component, inject } from '@angular/core';\nimport { TranslateService, TranslateDirective } from '@ngx-translate/core';\n\n@Component({\n  selector: 'app-header',\n  imports: [TranslateDirective],\n  template: `\n    \u003ch1 [translate]=\"'header.title'\"\u003e\u003c/h1\u003e\n    \u003cp\n      [translate]=\"'header.subtitle'\"\n      [translateParams]=\"{ version: '2.0' }\"\n    \u003e\u003c/p\u003e\n  `,\n})\nexport class HeaderComponent {\n  private translate = inject(TranslateService);\n}\n```\n\n### Translation File Format\n\nYour JSON translation files should use nested or flat structures:\n\n**Nested format (`en.json`):**\n\n```json\n{\n  \"app\": {\n    \"title\": \"My Application\",\n    \"welcome\": \"Welcome, {{name}}!\"\n  },\n  \"header\": {\n    \"title\": \"Dashboard\",\n    \"subtitle\": \"Version {{version}}\"\n  },\n  \"buttons\": {\n    \"save\": \"Save\",\n    \"cancel\": \"Cancel\"\n  }\n}\n```\n\n### Generating Translation Files\n\nUse the CLI to convert Excel files to Angular-compatible JSON:\n\n```bash\n# Convert Excel to Angular i18n files\ni18n-excel-manager excel-to-i18n \\\n  --input ./translations.xlsx \\\n  --output ./public/assets/i18n \\\n  --fail-on-duplicates\n```\n\n### Angular Configuration\n\nEnsure `public/` is included in your `angular.json` assets:\n\n```json\n{\n  \"projects\": {\n    \"my-app\": {\n      \"architect\": {\n        \"build\": {\n          \"options\": {\n            \"assets\": [\"public\"]\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n### Best Practices\n\n- **Version Control**: Commit translation files to git for version history.\n- **CI/CD Integration**: Run `analyze` in your pipeline to catch missing translations.\n- **Language Detection**: Use browser language or user preferences for initial language.\n- **Lazy Loading**: Consider splitting translations per feature for large applications.\n- **Validation**: Use `--dry-run` to validate translations before deployment.\n- **Placeholder Consistency**: Use consistent placeholder names across all languages.\n\n---\n\n## ⚙️ Configuration\n\nCreate a `config.json` file for custom settings. The CLI automatically loads `./config.json` from your current working\ndirectory when present.\n\n```json\n{\n  \"languages\": {\n    \"en\": \"English\",\n    \"de\": \"Deutsch\",\n    \"fr\": \"Français\",\n    \"es\": \"Spanish\"\n  },\n  \"defaults\": {\n    \"sourcePath\": \"./public/assets/i18n\",\n    \"targetFile\": \"translations.xlsx\",\n    \"targetPath\": \"./public/assets/i18n\",\n    \"sheetName\": \"Translations\"\n  }\n}\n```\n\n### Configuration Precedence\n\nCLI options take precedence over config file settings:\n\n```\nCLI flags \u003e config.defaults \u003e built-in defaults\n```\n\nLanguage map precedence:\n\n```\nCLI \u003e config.languages \u003e runtime config\n```\n\n### Usage Examples\n\n```bash\n# Autoload from CWD\ni18n-excel-manager i18n-to-excel --dry-run\n\n# Custom config path\ni18n-excel-manager i18n-to-excel --config ./my-config.json --dry-run\n\n# CLI flags override config\ni18n-excel-manager i18n-to-excel -i ./custom -o out.xlsx --dry-run\n```\n\n\u003e **Note:** For safety, `--config` must point within the current working directory.\n\n---\n\n## 📋 CLI Options Reference\n\n### `init` Command\n\n| Option               | Short | Description                                  | Default               |\n| -------------------- | ----- | -------------------------------------------- | --------------------- |\n| `--output \u003cpath\u003e`    | `-o`  | Target directory for i18n JSON files         | `public/assets/i18n`  |\n| `--languages \u003clist\u003e` | `-l`  | Comma-separated language codes to initialize | prompts interactively |\n| `--dry-run`          | `-d`  | Simulate only, do not write files            | `false`               |\n| `--config \u003cfile\u003e`    |       | Path to config file                          | `./config.json`       |\n\n### `i18n-to-excel` Command\n\n| Option                | Short | Description                                  | Default                  |\n| --------------------- | ----- | -------------------------------------------- | ------------------------ |\n| `--input \u003cpath\u003e`      | `-i`  | Path to directory containing i18n JSON files | `public/assets/i18n`     |\n| `--output \u003cfile\u003e`     | `-o`  | Path for the output Excel file               | `dist/translations.xlsx` |\n| `--sheet-name \u003cname\u003e` | `-s`  | Excel worksheet name                         | `Translations`           |\n| `--dry-run`           | `-d`  | Simulate only, do not write files            | `false`                  |\n| `--no-report`         |       | Skip generating translation report           | `false`                  |\n| `--config \u003cfile\u003e`     |       | Path to config file                          | `./config.json`          |\n\n### `excel-to-i18n` Command\n\n| Option                 | Short | Description                          | Default                  |\n| ---------------------- | ----- | ------------------------------------ | ------------------------ |\n| `--input \u003cfile\u003e`       | `-i`  | Path to Excel file                   | `dist/translations.xlsx` |\n| `--output \u003cpath\u003e`      | `-o`  | Target directory for i18n JSON files | `locales`                |\n| `--sheet-name \u003cname\u003e`  | `-s`  | Excel worksheet name                 | `Translations`           |\n| `--dry-run`            | `-d`  | Simulate only, do not write files    | `false`                  |\n| `--fail-on-duplicates` |       | Exit with error on duplicate keys    | `false`                  |\n| `--config \u003cfile\u003e`      |       | Path to config file                  | `./config.json`          |\n\n### `analyze` Command\n\n| Option                 | Short | Description                                  | Default             |\n| ---------------------- | ----- | -------------------------------------------- | ------------------- |\n| `--input \u003cpath\u003e`       | `-i`  | Path to directory containing i18n JSON files | -                   |\n| `--pattern \u003cglob\u003e`     | `-p`  | Glob pattern for source code files           | `**/*.{html,ts,js}` |\n| `--translate`          |       | Enable AI auto-translation mode              | `false`             |\n| `--api-key \u003ckey\u003e`      |       | Gemini API key (or use env vars)             | -                   |\n| `--source-lang \u003ccode\u003e` |       | Source language code for translation         | `en`                |\n| `--model \u003cmodel\u003e`      |       | Gemini model to use                          | `gemini-2.5-flash`  |\n| `--config \u003cfile\u003e`      |       | Path to config file                          | `./config.json`     |\n\n---\n\n## 🔄 Migration Guide\n\n### From v1.x to v2.x\n\nIn v2.x, we removed legacy CLI command aliases to enforce explicit command names for better clarity and consistency.\n\n#### Breaking Changes\n\n- Removed `to-excel` alias for `i18n-to-excel` command.\n- Removed `to-json` alias for `excel-to-i18n` command.\n\n#### Migration Steps\n\n1. Update your scripts to use the full command names:\n   - Change `i18n-excel-manager to-excel ...` to `i18n-excel-manager i18n-to-excel ...`\n   - Change `i18n-excel-manager to-json ...` to `i18n-excel-manager excel-to-i18n ...`\n2. If you were using the aliases in CI/CD pipelines or automation scripts, update them accordingly.\n3. No other changes are required; all other options and functionality remain the same.\n\nIf you encounter issues, use `i18n-excel-manager --help` to see available commands.\n\n---\n\n## 🚨 Error Handling\n\nThe tool provides clear error messages for common issues:\n\n| Error Type             | Message Example                                            |\n| ---------------------- | ---------------------------------------------------------- |\n| Missing files          | `File does not exist: path`                                |\n| Invalid JSON           | `Invalid JSON in file: error message`                      |\n| Duplicate keys         | `Duplicate keys detected in Excel: key1, key2`             |\n| Invalid language codes | `Invalid language code: xyz`                               |\n| Unsafe paths           | `Unsafe output path: path`                                 |\n| Missing API key        | `API Key is missing. Pass --api-key or set GEMINI_API_KEY` |\n\nUse `--dry-run` to validate before actual conversion.\n\n### Troubleshooting\n\n| Issue                  | Solution                                                 |\n| ---------------------- | -------------------------------------------------------- |\n| Permission errors      | Ensure you have write access to the output directory     |\n| Invalid language codes | Use standard ISO language codes (e.g., `en`, `de`, `fr`) |\n| Missing placeholders   | Check for consistent placeholder usage across languages  |\n| Large files            | Consider splitting into multiple sheets                  |\n| API rate limits        | Use batch processing or add delays between requests      |\n\n---\n\n## 🏗️ Architecture\n\nThe project follows a modular architecture with clear separation of concerns:\n\n```\nsrc/\n├── app/           # Application orchestration layer\n│   ├── analyze.js     # Codebase analysis orchestrator\n│   ├── convert.js     # Conversion orchestrator\n│   └── translate.js   # AI translation orchestrator\n├── core/          # Business logic (pure functions)\n│   ├── analyzer.js    # Key extraction and comparison\n│   ├── translator.js  # Gemini API integration\n│   ├── excel/         # Excel data processing\n│   ├── json/          # JSON structure handling\n│   └── languages/     # Language mapping utilities\n├── io/            # I/O operations\n│   ├── excel.js       # Excel file read/write\n│   ├── fs.js          # File system operations\n│   └── config.js      # Configuration loading\n├── cli/           # CLI interface\n│   ├── commands.js    # Command handlers\n│   ├── interactive.js # Interactive menu\n│   └── init.js        # Initialization logic\n└── reporters/     # Output formatting\n    ├── console.js     # Console reporter\n    └── json.js        # JSON reporter\n```\n\n### Design Principles\n\n- **Modular Design**: Separate concerns for I/O, core logic, and reporting.\n- **Pure Functions**: Core business logic is testable and side-effect free.\n- **Dependency Injection**: I/O adapters are injectable for testing.\n- **Validation**: Input validation at all boundaries.\n- **Extensibility**: Pluggable reporters and configurable I/O layers.\n\n---\n\n## ⚠️ Known Issues\n\n### Language Mapping After AI Auto-Translation\n\nThere is a known issue when exporting back from Excel to JSON after using the AI auto-translator where the language\nmapping may not work properly.\n\n**Workaround:** Restart `i18n-excel-manager` and try the export again.\n\nThis issue is being tracked and will be fixed in a future release.\n\n---\n\n## 🧑‍💻 Development\n\n### Prerequisites\n\n- Node.js \u003e= 20\n- npm or yarn\n\n### Setup\n\n```bash\ngit clone https://github.com/mariokreitz/i18n-excel-manager.git\ncd i18n-excel-manager\nnpm install\n```\n\n### Running Tests\n\n```bash\n# Run all tests\nnpm test\n\n# Run tests with coverage\nnpm run test:coverage\n```\n\n### Linting\n\n```bash\n# Check for lint errors\nnpm run lint\n\n# Fix lint errors\nnpm run lint:fix\n```\n\n### Formatting\n\n```bash\n# Check formatting\nnpm run format:check\n\n# Fix formatting\nnpm run format\n```\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! Please read the [Contributing Guide](CONTRIBUTING.md)\nand [Code of Conduct](CODE_OF_CONDUCT.md) before submitting a pull request.\n\n### Quick Contribution Steps\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/amazing-feature`\n3. Make your changes\n4. Run tests: `npm test`\n5. Commit your changes: `git commit -m 'Add amazing feature'`\n6. Push to the branch: `git push origin feature/amazing-feature`\n7. Open a Pull Request\n\n---\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n\u003cp align=\"center\"\u003e\n  Made with ❤️ by \u003ca href=\"https://github.com/mariokreitz\"\u003eMario Kreitz\u003c/a\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmariokreitz%2Fi18n-excel-manager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmariokreitz%2Fi18n-excel-manager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmariokreitz%2Fi18n-excel-manager/lists"}