excel-i18n-editor (workspace)

This workspace bridges translator-friendly Excel workflows with developer-friendly JSON i18n pipelines, reducing Excel-to-JSON drift, hard-to-review changes, and key inconsistency risks.

Prerequisites

• Node.js 20 (matches CI)
• Access to the internal npm registry and this repo

Clone

git clone https://github.com/moojing/excel-i18n-editor.git
cd excel-i18n-editor

Install

npm install

Project layout

• scripts/resolve-config.* - load settings from config files and env vars for app startup
• app/ - optional web editor UI
• config.json - default runtime config

Start the editor UI

This repository ships with the app/ folder, the Vite config, and the editor npm scripts (npm run editor, npm run editor:web, and npm run editor:server) so you can work on the editor directly after cloning and running npm install. Copy any custom config into config.json (or pass --config) before starting the server.

npm run editor uses concurrently to run the backend (tsx watch app/server/index.ts) and the Vite dev server (vite app --config app/vite.config.ts). If you only need the API, run npm run editor:server alone. If the Vite dev server takes a moment to start, the script already waits for port 3030 before launching the web client.

Third-party users can now start the editor directly from npm without cloning this repository:

npx @moojing/excel-i18n-editor editor

Default API port is 3030. To change it, pass --port:

npx @moojing/excel-i18n-editor editor --port 4040

To use a custom config file:

npx @moojing/excel-i18n-editor editor --config ./my-project/config.json --port 4040

The command runs both the API server and the Vite UI, resolves config.json, xlsx/, and translations/ from the caller's current working directory (not from inside node_modules), and automatically updates both ports:

• API server uses --port (default 3030)
• frontend dev server uses --port + 1 (for example 4041 when --port 4040) and proxies /api to the API server

Quick start

1. (Optional) Create a config file if you want custom folders or multiple environments, for example ./my-project/config.json:

{
  "sourceExcelDir": "./my-project/xlsx",
  "outputI18nDir": "./my-project/translations",
  "workbookFilename": "source.xlsx",
  "apiPort": 3030,
  "afterSaveHook": "excel-to-json"
}

If your config file is not ./config.json, use EXCEL_I18N_EDITOR_CONFIG=... or pass --config ....

Convert Excel to JSON

Run:

npm run excel-to-json

This generates translations into outputI18nDir from sourceExcelDir using config.json. Use EXCEL_I18N_EDITOR_CONFIG=... or --config ... only when config is not ./config.json.

excel-to-json supports CLI overrides (CLI args win over config values):

# override source/output dirs
npm run excel-to-json -- --input ./xlsx --output ./translations

# convert a specific workbook only
npm run excel-to-json -- --workbook source.xlsx

# use another config file
npm run excel-to-json -- --config ./my-project/config.json

Convert JSON to Excel

Run:

npm run json-to-excel

By default this converts the module matching workbookFilename in config (for example source) and writes to sourceExcelDir/workbookFilename.

Useful variants:

# convert a specific module
npm run json-to-excel -- --module auroraNotebook

# convert all modules found in translations
npm run json-to-excel -- --all

# preview without writing files
npm run json-to-excel -- --dry-run

# use another config file
npm run json-to-excel -- --config ./my-project/config.json

Editor save and sync behavior

• POST /api/workbook always saves workbook changes, then executes afterSaveHook.
• afterSaveHook supports:
  • "excel-to-json" (default): run excel-to-json after save.
  • "none": save workbook only.
• POST /api/sync still provides a manual way to run excel-to-json.
• Frontend Auto Save uses debounce and only saves workbook data (skipAfterSaveHook: true) to avoid running excel-to-json on every keystroke.

Support

For any issues, please contact maintainers.