CSV to i18n TypeScript Converter (csv-i18n)

A command-line tool to recursively find CSV files in a specified directory, parse them, and generate TypeScript files (one per language) containing flat key-value pairs suitable for internationalization (i18n).

Installation

# Install globally (if needed)
npm install -g .

# Or run directly using npx
# npx . --input <input-dir> --output <output-file>

(Note: For publishing to npm or GitHub Packages, you'd typically install by package name after publishing.)

Usage

csv-i18n --input <path/to/csv/directory> --output <path/to/output/directory>

Or using npx:

npx . --input <path/to/csv/directory> --output <path/to/output/directory>

Options

• -i, --input <dir>: (Required) The input directory containing the CSV files. The tool will search this directory recursively.
• -o, --output <dir>: (Required) The path to the output directory where the generated files (e.g., ja.ts, en.ts or ja.json, en.json) should be saved. The directory will be created if it doesn't exist.
• -f, --format <type>: (Optional) The output format type. Can be typescript (default) or i18next (generates nested JSON).
• -w, --watch: (Optional) Watch the input directory for changes and automatically re-run the conversion. Press Ctrl+C to stop watching. 33 |

CSV Format

• Files must have a .csv extension.
• Files must be UTF-8 encoded.
• The first row must be a header row.
• There must be a column named key (case-insensitive check, but prefer lowercase key). This column contains the final part of the translation key.
• All other columns are treated as language codes (e.g., ja, en, fr). The values in these columns are the translations for that language.
• Empty cells or cells with only whitespace will be ignored for that specific language key.
• Rows without a valid key will be skipped with a warning.

TypeScript Output Structure

The tool generates the following files in the specified output directory:

1. Language Files (<lang>.ts): One TypeScript file per detected language (e.g., ja.ts, en.ts). Each file exports a default object containing flat key-value pairs for that language. The keys are constructed by combining the relative path of the CSV file (from the input directory, using dots as separators) and the key value from the CSV.
2. Key File (key.ts): A single TypeScript file that exports a default object containing all unique translation keys found across all CSV files. Both the keys and values in this object are the translation key strings (e.g., { "common.greeting": "common.greeting", ... }). This can be useful for type safety or referencing keys in code.

Example:

If the input directory is locales/csv and contains:

• locales/csv/common.csv:

  key,ja,en
  greeting,こんにちは,Hello

• locales/csv/components/button.csv:

  key,ja,en
  submit,送信,Submit
  cancel,キャンセル,Cancel

Running csv-i18n --input locales/csv --output dist/ts would produce the following files in the dist/ts directory:

• dist/ts/ja.ts:

  // Auto-generated by csv-i18n tool. Do not edit manually.
  export default {
    "common.greeting": "こんにちは",
    "common.farewell": "さようなら",
    "components.button.submit": "送信",
    "components.button.cancel": "キャンセル"
  };

• dist/ts/en.ts:

  // Auto-generated by csv-i18n tool. Do not edit manually.
  export default {
    "common.greeting": "Hello",
    "common.farewell": "Goodbye",
    "components.button.submit": "Submit",
    "components.button.cancel": "Cancel"
  };

• (And potentially fr.ts if the fr column exists in the CSVs)
• dist/ts/key.ts:

  // Auto-generated by csv-i18n tool. Do not edit manually.
  export default {
    "common.farewell": "common.farewell",
    "common.greeting": "common.greeting",
    "components.button.cancel": "components.button.cancel",
    "components.button.submit": "components.button.submit"
  };

Development

1. Clone the repository.
2. Run npm install.
3. You can run the tool directly using node src/index.js --input ... --output ....