CLI tooling for localization workflows in TypeScript projects.

Documentation · Getting Started · CLI Reference · Configuration · VS Code Extension · Contributing

---

Why LangSync

LangSync helps you run day-to-day localization tasks from one CLI: initialize config, validate locale drift, sync missing keys, translate empty values, and handle Excel import/export when translators need spreadsheets.

• Translation synchronization — keep locale structures aligned automatically.
• Missing-key detection — catch drift early in development and CI.
• Strict validation — fail CI when a locale drifts.
• Framework integrations — drop-in support for i18next, ngx-translate, and react-intl.
• AI translation adapters — OpenAI and DeepL are released; Anthropic and Gemini are experimental (LANGSYNC_AI_EXPERIMENTAL=1).
• Optional Excel workflow — collaborate with translators when spreadsheet handoff is needed.
• Editor integration — a VS Code extension surfaces missing, extra, and empty keys inline as you work.
• Namespace support — scale from one file per locale to folder or prefix-based namespace layouts.
• Beautiful terminal UX — interactive prompts, spinners, and structured output.
• CI-ready — JSON reporters and proper exit codes for every command.

---

Getting Started

Install

pnpm add -D @mariokreitz/langsync
# or
npm install -D @mariokreitz/langsync
# or
yarn add -D @mariokreitz/langsync

Requires Node.js 22+ and an ESM-compatible project.

Initialize

Run the interactive setup. LangSync detects your i18n framework from package.json, scaffolds langsync.config.ts, and creates single-file or namespaced locale stubs.

npx langsync init

Validate

Check every configured locale against the reference locale.

npx langsync validate

Sync

Pull every key from the reference locale into the rest, preserving existing translations and inserting empty placeholders for new keys.

npx langsync sync

---

CLI Reference

Command	Description
langsync init	Initialize a typed langsync.config.ts and scaffold locale files.
langsync validate	Report missing, extra, and empty keys across locales/namespaces.
langsync find-missing	Report missing keys per locale; exits non-zero on errors.
langsync sync	Synchronize reference keys into each target locale or namespace.
langsync translate	Fill empty values in non-reference locales using an AI provider.
langsync watch	Watch locale files and run incremental sync + validation on change.
langsync export excel	Export locales/namespaces into a single .xlsx workbook.
langsync import excel	Import workbook translations back into configured JSON files.

The validate and find-missing commands support --reporter json for CI integrations. The sync, translate, and import excel commands support --dry-run for safe previews.

---

Configuration

Create a langsync.config.ts at the project root:

import { defineConfig } from '@mariokreitz/langsync';

export default defineConfig({
  input: './src/i18n',
  output: './translations',
  locales: ['en', 'de', 'fr'],
  defaultLocale: 'en',
  framework: 'i18next',
  // Opt in to namespaced files when your project outgrows one file per locale.
  // namespaces: { structure: 'locale-dir' }, // ./src/i18n/en/common.json
  // namespaces: { structure: 'locale-prefix' }, // ./src/i18n/en.common.json
  excel: {
    file: 'translations.xlsx',
    sheetName: 'Translations',
  },
  ai: {
    provider: 'openai',
    model: 'gpt-5-mini',
  },
});

Option	Type	Required	Description
input	string	yes	Path to the source i18n directory.
output	string	no	Output / translations directory (default ./translations).
locales	string[]	yes	List of supported locales.
defaultLocale	string	no	Reference locale used for validation and sync.
framework	string	no	One of i18next, ngx-translate, react-intl, none.
namespaces	object	no	Optional locale-dir or locale-prefix layout.
excel.file	string	no	Excel filename (default translations.xlsx).
excel.sheetName	string	no	Worksheet name (default Translations).
ai.provider	string	no	openai or deepl (released); anthropic / gemini require LANGSYNC_AI_EXPERIMENTAL=1.
ai.apiKey	string	no	API key (falls back to a provider env var).
ai.model	string	no	Provider model id (e.g. gpt-5-mini).

JSON, JS, and MJS config files are also supported via cosmiconfig. Omit namespaces for the default <input>/<locale>.json layout, or set namespaces.structure to locale-dir or locale-prefix for per-namespace files.

---

Framework Integrations

LangSync auto-detects the following i18n libraries during langsync init:

• i18next (incl. react-i18next, vue-i18next)
• ngx-translate (Angular)
• react-intl / @formatjs/intl

Omit framework or set framework: 'none' for custom setups.

---

CI Usage

- name: Validate translations
  run: npx langsync validate --reporter json

validate and find-missing exit with code 1 on missing or extra issues, making them safe drop-ins for pull-request checks.

---

Editor & SDK Integration

LangSync is more than a CLI:

• VS Code extension — surfaces missing, extra, and empty translation keys as native diagnostics while you work, with validate, sync, and find-missing commands in the Command Palette. See the VS Code Extension guide.
• SDK (@mariokreitz/langsync-sdk) — every command runner is exported as an in-process, side-effect-free function, so editor integrations, custom scripts, and CI tooling can drive the same workflows without shelling out. See the SDK reference.

---

Documentation

The full documentation lives at docs.langsync.kreitz-webdev.de and covers configuration, every CLI command, the VS Code extension, the SDK, and framework integration recipes.

The site (built with Fumadocs) lives under apps/docs and runs locally with:

pnpm --filter @langsync/docs dev

---

Migration from i18n-excel-manager

Migration guidance lives in the dedicated docs page:

• Migration from i18n-excel-manager

Use that guide for command mapping, config setup, and rollout steps.

---

Project Structure

LangSync is a TurboRepo monorepo of small, focused packages:

packages/
  cli/              # The `langsync` CLI (published to npm)
  core/             # Parsers, validators, sync engine
  excel-engine/     # Excel (xlsx) import/export
  ai-engine/        # AI translation adapters (OpenAI + DeepL; Anthropic + Gemini experimental)
  shared/           # Types, config loader, fs helpers, logger
  vscode-extension/ # VS Code extension (in-editor diagnostics)
apps/
  docs/             # Documentation site

---

Roadmap

V1 shipped the full local workflow: init, validate, sync, find-missing, Excel I/O, and framework detection.

V2 (current) adds:

• AI-assisted translation (langsync translate) with pluggable providers (OpenAI and DeepL released; Anthropic and Gemini behind an experimental flag).
• Watch mode and incremental sync (langsync watch).
• A reusable composite GitHub Action for validate and find-missing.
• A VS Code extension with in-editor diagnostics and command-palette workflows.

Future releases will explore:

• A web dashboard for translator collaboration.

---

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md for development setup, testing conventions, and the commit-message policy.

---

License

MIT © Mario Kreitz