@i18n-tools/i18n-csv-generator

A powerful Node.js tool to convert CSV files to i18n JSON files for JavaScript applications (React, Vue, Angular, etc.). Perfect for business users who need to manage translations without touching code.

🆕 New in v1.0.0: Enhanced JSON generation with better handling of empty values and improved validation! Perfect for teams that need robust translation management with comprehensive validation.

📋 Table of Contents

• Installation
• Quick Start
• System Requirements
• Usage
• API Reference
• Examples
• Configuration
• Validation
• Integration
• Contributing
• License

🚀 Installation

npm install @i18n-tools/i18n-csv-generator

Global Installation (CLI)

npm install -g @i18n-tools/i18n-csv-generator

⚡ Quick Start

Basic Usage

# Generate JSON files from CSV
npx i18n-generator generate --input translations.csv --output src/assets/i18n

# Validate CSV file
npx i18n-generator validate --input translations.csv

# Watch for changes
npx i18n-generator watch --input translations.csv --output src/assets/i18n

# Generate CSV from existing English JSON file
npx i18n-generator from-json --input en.json --output translations.csv --languages en,mr,es

# Validate JSON files against CSV
npx i18n-generator validate-json --input translations.csv --json-dir src/assets/i18n

Programmatic Usage

import { I18nGenerator } from '@bhushan001/i18n-csv-generator';

const generator = new I18nGenerator({
  inputFile: 'translations.csv',
  outputDir: 'src/assets/i18n',
  languages: ['eng', 'mr'],
  backup: true
});

await generator.generate();

💻 System Requirements

Minimum Requirements

• Node.js: >= 18.0.0
• npm: >= 8.0.0
• Operating System:
  • macOS 10.15+ (Catalina)
  • Windows 10+ (64-bit)
  • Linux (Ubuntu 18.04+, CentOS 7+, RHEL 7+)

Recommended Requirements

• Node.js: >= 20.0.0 (LTS)
• npm: >= 9.0.0
• Memory: 512MB RAM
• Disk Space: 50MB free space

Browser Support

This package is designed for Node.js environments and does not support browser usage.

Dependencies

Production Dependencies

• csv-parser: ^3.0.0 - CSV parsing
• csv-writer: ^1.6.0 - CSV writing
• chokidar: ^3.5.3 - File watching

Development Dependencies

• typescript: ^4.9.0 - TypeScript compilation
• @types/node: ^18.0.0 - Node.js type definitions

📖 Usage

CSV Format

The CSV file must follow this structure:

path,description,eng,mr
common.loading,Loading text shown during data fetch,Loading...,लोड होत आहे...
auth.login,Login button text,Login,लॉगिन
navigation.dashboard,Dashboard menu item,Dashboard,डॅशबोर्ड

Required Columns

| Column | Type | Description | Example | |--------|------|-------------|---------| | path | string | Translation key using dot notation | section.subsection.key | | description | string | Human-readable description | Login button text | | [lang] | string | Translation for specific language | Login |

Path Format Rules

• Use dot notation: section.subsection.key
• Start with letter: [a-zA-Z]
• Alphanumeric characters: [a-zA-Z0-9]
• No spaces or special characters
• Maximum 10 levels deep

Valid Examples:

• common.loading
• auth.login
• navigation.dashboard
• members.addMember

Invalid Examples:

• common-loading (hyphens not allowed)
• 1section.key (cannot start with number)
• section..key (double dots not allowed)

🔧 CLI Commands

Generate JSON Files

i18n-generator generate --input <csv-file> --output <json-directory> [options]

Options:

• --input, -i (required): Path to CSV file
• --output, -o (required): Output directory for JSON files
• --backup, -b (optional): Create backup of existing files

Example:

i18n-generator generate --input translations.csv --output src/assets/i18n --backup

Validate CSV

i18n-generator validate --input <csv-file>

Options:

• --input, -i (required): Path to CSV file

Example:

i18n-generator validate --input translations.csv

Validate JSON Files

i18n-generator validate-json --input <csv-file> --json-dir <json-directory>

Options:

• --input, -i (required): Path to CSV file
• --json-dir, -j (required): Directory containing JSON files

Example:

i18n-generator validate-json --input translations.csv --json-dir src/assets/i18n

This command validates that all JSON files have the same translation keys as the CSV file, ensuring consistency between source and generated files.

Watch Mode

i18n-generator watch --input <csv-file> --output <json-directory>

Options:

• --input, -i (required): Path to CSV file
• --output, -o (required): Output directory for JSON files

Example:

i18n-generator watch --input translations.csv --output src/assets/i18n

Export JSON to CSV

i18n-generator export --input <json-directory> --output <csv-file>

Options:

• --input, -i (required): Directory containing JSON files
• --output, -o (required): Output CSV file path

Example:

i18n-generator export --input src/assets/i18n --output exported.csv

Create Template

i18n-generator init --output <csv-file>

Options:

• --output, -o (required): Output CSV file path

Example:

i18n-generator init --output sample.csv

Generate CSV from English JSON

i18n-generator from-json --input <english-json-file> --output <csv-file> [--languages <lang1,lang2,...>]

Options:

• --input, -i (required): Path to existing English JSON file
• --output, -o (required): Output CSV file path
• --languages, -l (optional): Target languages (default: en,mr)

Example:

i18n-generator from-json --input src/assets/i18n/en.json --output translations.csv --languages en,mr,es

📚 API Reference

I18nGenerator

Main class for generating i18n JSON files from CSV.

Constructor

new I18nGenerator(config: GeneratorConfig)

Configuration Interface

interface GeneratorConfig {
  inputFile: string;           // Path to CSV file
  outputDir: string;          // Output directory for JSON files
  languages: string[];        // Language codes (auto-detected if empty)
  defaultLanguage?: string;   // Default language code
  validateOnly?: boolean;     // Only validate, don't generate
  watch?: boolean;           // Watch mode for file changes
  backup?: boolean;          // Create backup of existing files
}

Methods

generate()

Generates JSON files from CSV.

async generate(): Promise<void>

Returns: Promise that resolves when generation is complete

Throws: Error if validation fails or file operations fail

validate()

Validates CSV file without generating JSON.

async validate(): Promise<ValidationResult>

Returns: Promise with validation results

watch()

Watches CSV file for changes and regenerates automatically.

async watch(): Promise<void>

Returns: Promise that never resolves (keeps watching)

exportToCsv()

Exports existing JSON files to CSV format.

async exportToCsv(outputCsvPath: string): Promise<void>

Parameters:

• outputCsvPath: Path to output CSV file

Returns: Promise that resolves when export is complete

Static Methods

createSampleCsv()

Creates a sample CSV template.

static createSampleCsv(outputPath: string, languages?: string[]): void

Parameters:

• outputPath: Path to output CSV file
• languages: Array of language codes (default: ['eng', 'mr'])

generateCsvFromEnglishJson()

Generates CSV from existing English JSON file. Useful when you already have English translations and want to add other languages.

static generateCsvFromEnglishJson(
  englishJsonPath: string,
  outputCsvPath: string,
  targetLanguages?: string[]
): Promise<void>

Parameters:

• englishJsonPath: Path to existing English JSON file
• outputCsvPath: Path to output CSV file
• targetLanguages: Array of target language codes (default: ['en', 'mr'])

Returns: Promise that resolves when CSV generation is complete

Example:

await I18nGenerator.generateCsvFromEnglishJson(
  'src/assets/i18n/en.json',
  'translations.csv',
  ['en', 'mr', 'es']
);

validateJsonAgainstCsv()

Validates JSON files against CSV data to ensure consistency between source and generated files.

static validateJsonAgainstCsv(
  csvFilePath: string,
  jsonDir: string
): Promise<void>

Parameters:

• csvFilePath: Path to CSV file
• jsonDir: Directory containing JSON files

Returns: Promise that resolves when validation is complete

Example:

await I18nGenerator.validateJsonAgainstCsv(
  'translations.csv',
  'src/assets/i18n'
);

🔄 Workflows

Workflow 1: Starting from Scratch

1. Create CSV template: i18n-generator init --output translations.csv
2. Add translations: Edit the CSV file with your translations
3. Generate JSON files: i18n-generator generate --input translations.csv --output src/assets/i18n

Workflow 2: Adding Languages to Existing English Translations

If you already have English translations in JSON format and want to add other languages:

1. Generate CSV from English JSON:

   i18n-generator from-json --input src/assets/i18n/en.json --output translations.csv --languages en,mr,es

2. Add translations for other languages: Open the CSV file and fill in translations for mr and es columns

3. Generate all JSON files:

   i18n-generator generate --input translations.csv --output src/assets/i18n

Example English JSON (en.json):

{
  "common": {
    "loading": "Loading...",
    "error": "An error occurred"
  },
  "auth": {
    "login": "Login",
    "logout": "Logout"
  }
}

Generated CSV (translations.csv):

path,description,en,mr,es
common.loading,Loading - "Loading...",Loading...,,
common.error,Error - "An error occurred",An error occurred,,
auth.login,Login - "Login",Login,,
auth.logout,Logout - "Logout",Logout,,

After adding translations:

path,description,en,mr,es
common.loading,Loading - "Loading...",Loading...,लोड होत आहे...,Cargando...
common.error,Error - "An error occurred",An error occurred,एक त्रुटी आली,Se produjo un error
auth.login,Login - "Login",Login,लॉगिन,Iniciar sesión
auth.logout,Logout - "Logout",Logout,लॉगआउट,Cerrar sesión

Workflow 3: Validating JSON Consistency

To ensure your JSON files are consistent with your CSV source:

1. Generate JSON files from CSV:

   i18n-generator generate --input translations.csv --output src/assets/i18n

2. Validate JSON files against CSV:

   i18n-generator validate-json --input translations.csv --json-dir src/assets/i18n

3. Fix any inconsistencies if validation fails, then regenerate JSON files

This workflow helps maintain consistency between your CSV source and generated JSON files, especially useful in CI/CD pipelines or when multiple team members are working on translations.

📊 Examples

Input CSV

Output JSON Files

en.json:

{
  "common": {
    "loading": "Loading..."
  },
  "auth": {
    "login": "Login"
  },
  "navigation": {
    "dashboard": "Dashboard"
  },
  "members": {
    "title": "Members",
    "addMember": "Add Member"
  }
}

mr.json:

{
  "common": {
    "loading": "लोड होत आहे..."
  },
  "auth": {
    "login": "लॉगिन"
  },
  "navigation": {
    "dashboard": "डॅशबोर्ड"
  },
  "members": {
    "title": "सदस्य",
    "addMember": "सदस्य जोडा"
  }
}

⚙️ Configuration

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | I18N_GENERATOR_DEBUG | Enable debug logging | false | | I18N_GENERATOR_TIMEOUT | File operation timeout (ms) | 30000 |

Package.json Scripts

{
  "scripts": {
    "i18n:generate": "i18n-generator generate --input translations.csv --output src/assets/i18n",
    "i18n:validate": "i18n-generator validate --input translations.csv",
    "i18n:watch": "i18n-generator watch --input translations.csv --output src/assets/i18n",
    "i18n:export": "i18n-generator export --input src/assets/i18n --output exported.csv",
    "i18n:init": "i18n-generator init --output translations.csv"
  }
}

🔍 Validation

The tool performs comprehensive validation:

Validation Rules

| Rule | Type | Description | |------|------|-------------| | Required Columns | Error | path and description must exist | | Language Columns | Error | At least one language column required | | Path Format | Error | Must follow dot notation rules | | Duplicate Paths | Error | No duplicate translation keys | | Empty Translations | Warning | Missing translations flagged | | Special Characters | Warning | Characters that need escaping |

Validation Output

=== Validation Results ===

❌ ERRORS:
  Row 3, Column "path": Invalid path format. Use dot notation (e.g., section.subsection.key)
    Value: "invalid path"

⚠️  WARNINGS:
  Row 5, Column "mr": Translation for mr is empty

✅ CSV file is valid!

🔗 Integration

Angular Integration

1. Install Package

npm install @sanchay/i18n-csv-generator

2. Add Scripts

{
  "scripts": {
    "i18n:generate": "i18n-generator generate --input translations.csv --output src/assets/i18n",
    "i18n:validate": "i18n-generator validate --input translations.csv",
    "i18n:watch": "i18n-generator watch --input translations.csv --output src/assets/i18n"
  }
}

3. Configure Angular

// angular.json
{
  "projects": {
    "your-app": {
      "architect": {
        "build": {
          "options": {
            "assets": [
              "src/assets/i18n"
            ]
          }
        }
      }
    }
  }
}

4. Use in Angular

import { TranslateModule, TranslateLoader } from '@ngx-translate/core';
import { TranslateHttpLoader } from '@ngx-translate/http-loader';

export function HttpLoaderFactory(http: HttpClient) {
  return new TranslateHttpLoader(http, './assets/i18n/', '.json');
}

@NgModule({
  imports: [
    TranslateModule.forRoot({
      loader: {
        provide: TranslateLoader,
        useFactory: HttpLoaderFactory,
        deps: [HttpClient]
      }
    })
  ]
})
export class AppModule { }

CI/CD Integration

GitHub Actions

name: Generate i18n
on:
  push:
    paths:
      - 'translations.csv'

jobs:
  generate-i18n:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm install @sanchay/i18n-csv-generator
      - run: npx i18n-generator generate --input translations.csv --output src/assets/i18n
      - run: git add src/assets/i18n/
      - run: git commit -m "Update i18n files" || exit 0
      - run: git push

🐛 Troubleshooting

Common Issues

"CSV file not found"

• Ensure the CSV file path is correct
• Check file permissions
• Verify file exists in the specified location

"Invalid path format"

• Use dot notation: section.subsection.key
• Avoid special characters and spaces
• Start with a letter

"No language columns found"

• Ensure CSV has language columns (e.g., eng, mr)
• Check CSV header format
• Verify column names match expected format

"Permission denied"

• Check file and directory permissions
• Ensure write access to output directory
• Run with appropriate user privileges

Debug Mode

Enable debug logging:

I18N_GENERATOR_DEBUG=true npx i18n-generator generate --input translations.csv --output src/assets/i18n

🚀 Get Involved & Contribute

We'd love your help to make this tool even better! Whether you're a developer, designer, or just passionate about internationalization, there are many ways to contribute.

💡 Request Features

Have an idea for a new feature? We want to hear it!

• 🎯 Create a Feature Request: Open an issue with the "Feature Request" template
• 💬 Discuss Ideas: Join our GitHub Discussions to brainstorm with the community
• 📝 Share Use Cases: Tell us how you're using the tool and what could make it better

Popular Feature Requests:

• 🔄 Support for more file formats (Excel, Google Sheets)
• 🌐 Integration with translation services (Google Translate, DeepL)
• 📊 Advanced validation rules and custom validators
• 🎨 Web UI for non-technical users
• 🔌 Plugin system for custom transformations

🛠️ Contribute Code

Ready to roll up your sleeves? Here's how to get started:

Quick Start for Contributors

# Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/csv-to-i18n.git
cd csv-to-i18n

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Start development mode
npm run dev

Areas We Need Help With

• 🧪 Testing: Add more test cases, improve coverage
• 📚 Documentation: Improve README, add examples, create tutorials
• 🐛 Bug Fixes: Help squash bugs and improve reliability
• ⚡ Performance: Optimize CSV parsing and JSON generation
• 🌍 Internationalization: Add support for more languages and formats
• 🎨 UI/UX: Design improvements for CLI and future web interface

Contribution Guidelines

1. Fork the repository and create a feature branch
2. Follow the existing code style and add tests for new features
3. Update documentation for any new functionality
4. Submit a pull request with a clear description of changes
5. Join the discussion in the PR comments

🎉 Recognition

Contributors will be:

• 📝 Listed in our contributors file
• 🏆 Featured in release notes
• 🎯 Mentioned in our documentation
• 💝 Given early access to new features

🤝 Community

• 💬 Discussions: GitHub Discussions
• 🐛 Bug Reports: GitHub Issues
• 📧 Contact: Open an issue or start a discussion
• ⭐ Star the repo: Show your support!

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone repository
git clone https://github.com/bhushan001/csv-to-i18n.git
cd csv-to-i18n

# Install dependencies
npm install

# Build package
npm run build

# Run tests
npm test

# Run linting
npm run lint

Code Style

• Follow TypeScript best practices
• Use meaningful variable names
• Add JSDoc comments for public APIs
• Write comprehensive tests

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📖 Documentation: GitHub Wiki
• 📧 Contact: Open an issue or start a discussion

📈 Changelog

See CHANGELOG.md for a list of changes and version history.

Made with ❤️ by Bhushan Gadekar