https://github.com/mariokreitz/langsync
Sync translations between developers, translators, and Excel without chaos
https://github.com/mariokreitz/langsync
cli developer-tools excel i18n localization nodejs translation typescript
Last synced: 8 days ago
JSON representation
Sync translations between developers, translators, and Excel without chaos
- Host: GitHub
- URL: https://github.com/mariokreitz/langsync
- Owner: mariokreitz
- License: mit
- Created: 2026-05-28T14:47:13.000Z (21 days ago)
- Default Branch: main
- Last Pushed: 2026-06-08T07:49:21.000Z (10 days ago)
- Last Synced: 2026-06-08T09:16:22.453Z (10 days ago)
- Topics: cli, developer-tools, excel, i18n, localization, nodejs, translation, typescript
- Language: TypeScript
- Homepage: https://docs.langsync.kreitz-webdev.de/
- Size: 729 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- fucking-awesome-angular - langsync - CLI tooling for localization workflows in TypeScript projects. (Development Utilities / Internationalization)
- awesome-angular - langsync - CLI tooling for localization workflows in TypeScript projects. (Development Utilities / Internationalization)
README
**CLI tooling for localization workflows in TypeScript projects.**
[](https://www.npmjs.com/package/@mariokreitz/langsync)
[](https://www.npmjs.com/package/@mariokreitz/langsync-sdk)
[](https://github.com/mariokreitz/langsync/actions/workflows/ci.yml)
[](https://codecov.io/gh/mariokreitz/langsync)
[](https://nodejs.org)
[](./LICENSE)
[Documentation](https://docs.langsync.kreitz-webdev.de) ·
[Getting Started](#getting-started) ·
[CLI Reference](#cli-reference) ·
[Configuration](#configuration) ·
[VS Code Extension](https://docs.langsync.kreitz-webdev.de/docs/vscode-extension) ·
[Contributing](./CONTRIBUTING.md)
---
## 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
```bash
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.
```bash
npx langsync init
```
### Validate
Check every configured locale against the reference locale.
```bash
npx langsync validate
```
### Sync
Pull every key from the reference locale into the rest, preserving existing
translations and inserting empty placeholders for new keys.
```bash
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:
```ts
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 `/.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
```yaml
- 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](https://docs.langsync.kreitz-webdev.de/docs/vscode-extension).
- **SDK** ([`@mariokreitz/langsync-sdk`](https://www.npmjs.com/package/@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](https://docs.langsync.kreitz-webdev.de/docs/sdk).
---
## Documentation
The full documentation lives at
**[docs.langsync.kreitz-webdev.de](https://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](https://fumadocs.dev)) lives under
[`apps/docs`](./apps/docs) and runs locally with:
```bash
pnpm --filter @langsync/docs dev
```
---
## Migration from i18n-excel-manager
Migration guidance lives in the dedicated docs page:
- [Migration from i18n-excel-manager](https://docs.langsync.kreitz-webdev.de/docs/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](./CONTRIBUTING.md)
for development setup, testing conventions, and the commit-message policy.
---
## License
[MIT](./LICENSE) © Mario Kreitz