csv-i18n-converter

Convert CSV translation files to iOS (.strings), Android (strings.xml), and Web (JSON) i18n formats with a simple CLI tool.

Features

• 🚀 Multi-platform support: Convert to iOS, Android, and Web formats
• 📝 CSV input: Use simple CSV files with key-value translations
• ✅ Validation: Detects duplicate keys and optionally duplicate values
• 🔍 Strict mode: Enforce unique translation values with --strict flag
• 📊 Progress tracking: Verbose mode shows conversion progress
• 🌍 Multi-language: Support for any number of languages in one CSV file

Installation

npm install -g csv-i18n-converter

Or use it locally in your project:

npm install csv-i18n-converter

Note: After installation, you can use either csv-i18n-converter (full name) or csvic (shorthand) as the command.

Usage

Basic Usage

You can use either the full command name or the shorthand:

# Full command name
csv-i18n-converter --platform <platform> --input <csv-file> --output <output-dir>

# Shorthand (csvic)
csvic --platform <platform> --input <csv-file> --output <output-dir>

Options

• -p, --platform <type> (required): Target platform (ios, android, or json)
• -i, --input <path> (required): Path to CSV file or directory containing CSV files
• -o, --output <dir> (required): Output directory for generated files
• -d, --delimiter <char> (optional): CSV delimiter (default: ,)
• -v, --verbose (optional): Enable verbose logging
• --strict (optional): Enable strict mode to prevent duplicate translation values

Examples

Convert to iOS format

# Using full command name
csv-i18n-converter --platform ios --input master.csv --output ./locales

# Or using shorthand
csvic --platform ios --input master.csv --output ./locales

This will generate files in the following structure:

locales/
  ios/
    en.lproj/
      Localizable.strings
    id.lproj/
      Localizable.strings
    ...

Convert to Android format

csv-i18n-converter --platform android --input master.csv --output ./locales

This will generate files in the following structure:

locales/
  android/
    en/
      strings.xml
    id/
      strings.xml
    ...

Convert to Web (JSON) format

csv-i18n-converter --platform json --input master.csv --output ./locales

This will generate files in the following structure:

locales/
  web/
    en.json
    id.json
    ...

With verbose logging

# Using full command name
csv-i18n-converter --platform json --input master.csv --output ./locales --verbose

# Or using shorthand
csvic --platform json --input master.csv --output ./locales --verbose

Enable strict mode

# Using full command name
csv-i18n-converter --platform ios --input master.csv --output ./locales --strict

# Or using shorthand
csvic --platform ios --input master.csv --output ./locales --strict

Strict mode will error if duplicate translation values are found in any language column.

CSV Format

Your CSV file should follow this format:

key,en,id,fr,de,it,ja,ko,pt,ru,es,zh
hello_there,Hello there,Halo,Bonjour,Hallo,Ciao,こんにちは,안녕하세요,Olá,Привет,Hola,你好
hope_your_day_is_going_well,Hope your day is going well,Semoga hari Anda lancar,J'espère que votre journée se passe bien,Ich hoffe,Che ti va,今日はいい天気ですね,좋은 하루 보내세요,Espero que você tenha um bom dia,Хорошего дня,Que tengas un buen día,希望你今天过得愉快

Requirements:

• First column must be named key
• Remaining columns are language codes (e.g., en, id, fr, etc.)
• Each row represents a translation key with its values in different languages
• Keys starting with # or // are treated as comments and skipped

Generated Output Formats

iOS (.strings)

/* master */
"hello_there" = "Hello there";
"hope_your_day_is_going_well" = "Hope your day is going well";

Android (strings.xml)

<?xml version="1.0" encoding="utf-8"?>
<resources>
  <string name="hello_there">Hello there</string>
  <string name="hope_your_day_is_going_well">Hope your day is going well</string>
</resources>

Web (JSON)

{
	"hello_there": "Hello there",
	"hope_your_day_is_going_well": "Hope your day is going well"
}

Note: JSON files are automatically sorted alphabetically by key.

Error Handling

The converter validates your CSV file and will report errors for:

• Duplicate keys: Always detected and reported as errors
• Duplicate values (with --strict flag): Detected and reported as errors in strict mode
• Invalid CSV format: Missing key column or insufficient columns
• Missing input file: Input file or directory not found

Using as npm Scripts

You can also use it in your package.json scripts. Both commands work:

{
	"scripts": {
		"build:i18n": "csvic --platform json --input master.csv --output ./locales",
		"build:i18n:ios": "csvic --platform ios --input master.csv --output ./locales",
		"build:i18n:android": "csvic --platform android --input master.csv --output ./locales"
	}
}

Note: You can use either csv-i18n-converter or csvic in your scripts - both work identically.

Requirements

• Node.js >= 12.0.0

Changelog

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

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT © Arie Syukron