{"id":50733298,"url":"https://github.com/mariokreitz/langsync","last_synced_at":"2026-06-10T11:01:14.191Z","repository":{"id":361010997,"uuid":"1252465617","full_name":"mariokreitz/langsync","owner":"mariokreitz","description":"Sync translations between developers, translators, and Excel without chaos","archived":false,"fork":false,"pushed_at":"2026-06-08T07:49:21.000Z","size":746,"stargazers_count":2,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-08T09:16:22.453Z","etag":null,"topics":["cli","developer-tools","excel","i18n","localization","nodejs","translation","typescript"],"latest_commit_sha":null,"homepage":"https://docs.langsync.kreitz-webdev.de/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mariokreitz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-28T14:47:13.000Z","updated_at":"2026-06-08T07:23:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mariokreitz/langsync","commit_stats":null,"previous_names":["mariokreitz/langsync"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/mariokreitz/langsync","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mariokreitz%2Flangsync","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mariokreitz%2Flangsync/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mariokreitz%2Flangsync/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mariokreitz%2Flangsync/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mariokreitz","download_url":"https://codeload.github.com/mariokreitz/langsync/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mariokreitz%2Flangsync/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34149132,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","developer-tools","excel","i18n","localization","nodejs","translation","typescript"],"created_at":"2026-06-10T11:01:13.426Z","updated_at":"2026-06-10T11:01:14.181Z","avatar_url":"https://github.com/mariokreitz.png","language":"TypeScript","funding_links":[],"categories":["Development Utilities"],"sub_categories":["Internationalization"],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg width=\"898\" height=\"251\" alt=\"image\" src=\"https://github.com/user-attachments/assets/828625ad-9e97-4d25-bc0b-0cfc78659ffa\" /\u003e\n\n**CLI tooling for localization workflows in TypeScript projects.**\n\n[![npm: cli](https://img.shields.io/npm/v/@mariokreitz/langsync?style=flat-square\u0026color=2563eb\u0026label=npm%20cli)](https://www.npmjs.com/package/@mariokreitz/langsync)\n[![npm: sdk](https://img.shields.io/npm/v/@mariokreitz/langsync-sdk?style=flat-square\u0026color=7c3aed\u0026label=npm%20sdk)](https://www.npmjs.com/package/@mariokreitz/langsync-sdk)\n[![CI](https://img.shields.io/github/actions/workflow/status/mariokreitz/langsync/ci.yml?event=pull_request\u0026style=flat-square\u0026label=CI)](https://github.com/mariokreitz/langsync/actions/workflows/ci.yml)\n[![codecov](https://img.shields.io/codecov/c/github/mariokreitz/langsync?style=flat-square)](https://codecov.io/gh/mariokreitz/langsync)\n[![Node](https://img.shields.io/node/v/@mariokreitz/langsync?style=flat-square\u0026color=2563eb)](https://nodejs.org)\n[![License](https://img.shields.io/npm/l/@mariokreitz/langsync.svg?style=flat-square)](./LICENSE)\n\n[Documentation](https://docs.langsync.kreitz-webdev.de) ·\n[Getting Started](#getting-started) ·\n[CLI Reference](#cli-reference) ·\n[Configuration](#configuration) ·\n[VS Code Extension](https://docs.langsync.kreitz-webdev.de/docs/vscode-extension) ·\n[Contributing](./CONTRIBUTING.md)\n\n\u003c/div\u003e\n\n---\n\n## Why LangSync\n\nLangSync helps you run day-to-day localization tasks from one CLI: initialize\nconfig, validate locale drift, sync missing keys, translate empty values, and\nhandle Excel import/export when translators need spreadsheets.\n\n- **Translation synchronization** — keep locale structures aligned automatically.\n- **Missing-key detection** — catch drift early in development and CI.\n- **Strict validation** — fail CI when a locale drifts.\n- **Framework integrations** — drop-in support for `i18next`, `ngx-translate`, and `react-intl`.\n- **AI translation adapters** — OpenAI and DeepL are released; Anthropic and Gemini are experimental (`LANGSYNC_AI_EXPERIMENTAL=1`).\n- **Optional Excel workflow** — collaborate with translators when spreadsheet handoff is needed.\n- **Editor integration** — a VS Code extension surfaces missing, extra, and empty keys inline as you work.\n- **Namespace support** — scale from one file per locale to folder or prefix-based namespace layouts.\n- **Beautiful terminal UX** — interactive prompts, spinners, and structured output.\n- **CI-ready** — JSON reporters and proper exit codes for every command.\n\n---\n\n## Getting Started\n\n### Install\n\n\u003c!-- embedme docs/shared/install.sh --\u003e\n\n```bash\npnpm add -D @mariokreitz/langsync\n# or\nnpm install -D @mariokreitz/langsync\n# or\nyarn add -D @mariokreitz/langsync\n\n\n```\n\n\u003e Requires **Node.js 22+** and an ESM-compatible project.\n\n### Initialize\n\nRun the interactive setup. LangSync detects your i18n framework from\n`package.json`, scaffolds `langsync.config.ts`, and creates single-file or namespaced locale stubs.\n\n```bash\nnpx langsync init\n```\n\n### Validate\n\nCheck every configured locale against the reference locale.\n\n```bash\nnpx langsync validate\n```\n\n### Sync\n\nPull every key from the reference locale into the rest, preserving existing\ntranslations and inserting empty placeholders for new keys.\n\n```bash\nnpx langsync sync\n```\n\n---\n\n## CLI Reference\n\n| Command                 | Description                                                         |\n| ----------------------- | ------------------------------------------------------------------- |\n| `langsync init`         | Initialize a typed `langsync.config.ts` and scaffold locale files.  |\n| `langsync validate`     | Report missing, extra, and empty keys across locales/namespaces.    |\n| `langsync find-missing` | Report missing keys per locale; exits non-zero on errors.           |\n| `langsync sync`         | Synchronize reference keys into each target locale or namespace.    |\n| `langsync translate`    | Fill empty values in non-reference locales using an AI provider.    |\n| `langsync watch`        | Watch locale files and run incremental sync + validation on change. |\n| `langsync export excel` | Export locales/namespaces into a single `.xlsx` workbook.           |\n| `langsync import excel` | Import workbook translations back into configured JSON files.       |\n\nThe `validate` and `find-missing` commands support `--reporter json` for CI\nintegrations. The `sync`, `translate`, and `import excel` commands support\n`--dry-run` for safe previews.\n\n---\n\n## Configuration\n\nCreate a `langsync.config.ts` at the project root:\n\n\u003c!-- embedme docs/shared/config.ts --\u003e\n\n```ts\nimport { defineConfig } from '@mariokreitz/langsync';\n\nexport default defineConfig({\n  input: './src/i18n',\n  output: './translations',\n  locales: ['en', 'de', 'fr'],\n  defaultLocale: 'en',\n  framework: 'i18next',\n  // Opt in to namespaced files when your project outgrows one file per locale.\n  // namespaces: { structure: 'locale-dir' }, // ./src/i18n/en/common.json\n  // namespaces: { structure: 'locale-prefix' }, // ./src/i18n/en.common.json\n  excel: {\n    file: 'translations.xlsx',\n    sheetName: 'Translations',\n  },\n  ai: {\n    provider: 'openai',\n    model: 'gpt-5-mini',\n  },\n});\n```\n\n| Option            | Type       | Required | Description                                                                                  |\n| ----------------- | ---------- | -------- | -------------------------------------------------------------------------------------------- |\n| `input`           | `string`   | yes      | Path to the source i18n directory.                                                           |\n| `output`          | `string`   | no       | Output / translations directory (default `./translations`).                                  |\n| `locales`         | `string[]` | yes      | List of supported locales.                                                                   |\n| `defaultLocale`   | `string`   | no       | Reference locale used for validation and sync.                                               |\n| `framework`       | `string`   | no       | One of `i18next`, `ngx-translate`, `react-intl`, `none`.                                     |\n| `namespaces`      | `object`   | no       | Optional `locale-dir` or `locale-prefix` layout.                                             |\n| `excel.file`      | `string`   | no       | Excel filename (default `translations.xlsx`).                                                |\n| `excel.sheetName` | `string`   | no       | Worksheet name (default `Translations`).                                                     |\n| `ai.provider`     | `string`   | no       | `openai` or `deepl` (released); `anthropic` / `gemini` require `LANGSYNC_AI_EXPERIMENTAL=1`. |\n| `ai.apiKey`       | `string`   | no       | API key (falls back to a provider env var).                                                  |\n| `ai.model`        | `string`   | no       | Provider model id (e.g. `gpt-5-mini`).                                                       |\n\nJSON, JS, and MJS config files are also supported via cosmiconfig. Omit `namespaces` for the default `\u003cinput\u003e/\u003clocale\u003e.json` layout, or set `namespaces.structure` to `locale-dir` or `locale-prefix` for per-namespace files.\n\n---\n\n## Framework Integrations\n\nLangSync auto-detects the following i18n libraries during `langsync init`:\n\n- **i18next** (incl. `react-i18next`, `vue-i18next`)\n- **ngx-translate** (Angular)\n- **react-intl** / `@formatjs/intl`\n\nOmit `framework` or set `framework: 'none'` for custom setups.\n\n---\n\n## CI Usage\n\n```yaml\n- name: Validate translations\n  run: npx langsync validate --reporter json\n```\n\n`validate` and `find-missing` exit with code `1` on `missing` or `extra`\nissues, making them safe drop-ins for pull-request checks.\n\n---\n\n## Editor \u0026 SDK Integration\n\nLangSync is more than a CLI:\n\n- **VS Code extension** — surfaces missing, extra, and empty translation keys as\n  native diagnostics while you work, with validate, sync, and find-missing\n  commands in the Command Palette. See the\n  [VS Code Extension guide](https://docs.langsync.kreitz-webdev.de/docs/vscode-extension).\n- **SDK** ([`@mariokreitz/langsync-sdk`](https://www.npmjs.com/package/@mariokreitz/langsync-sdk)) —\n  every command runner is exported as an\n  in-process, side-effect-free function, so editor integrations, custom scripts,\n  and CI tooling can drive the same workflows without shelling out. See the\n  [SDK reference](https://docs.langsync.kreitz-webdev.de/docs/sdk).\n\n---\n\n## Documentation\n\nThe full documentation lives at\n**[docs.langsync.kreitz-webdev.de](https://docs.langsync.kreitz-webdev.de)** and\ncovers configuration, every CLI command, the VS Code extension, the SDK, and\nframework integration recipes.\n\nThe site (built with [Fumadocs](https://fumadocs.dev)) lives under\n[`apps/docs`](./apps/docs) and runs locally with:\n\n```bash\npnpm --filter @langsync/docs dev\n```\n\n---\n\n## Migration from i18n-excel-manager\n\nMigration guidance lives in the dedicated docs page:\n\n- [Migration from i18n-excel-manager](https://docs.langsync.kreitz-webdev.de/docs/migration-from-i18n-excel-manager)\n\nUse that guide for command mapping, config setup, and rollout steps.\n\n---\n\n## Project Structure\n\nLangSync is a TurboRepo monorepo of small, focused packages:\n\n```\npackages/\n  cli/              # The `langsync` CLI (published to npm)\n  core/             # Parsers, validators, sync engine\n  excel-engine/     # Excel (xlsx) import/export\n  ai-engine/        # AI translation adapters (OpenAI + DeepL; Anthropic + Gemini experimental)\n  shared/           # Types, config loader, fs helpers, logger\n  vscode-extension/ # VS Code extension (in-editor diagnostics)\napps/\n  docs/             # Documentation site\n```\n\n---\n\n## Roadmap\n\nV1 shipped the full local workflow: init, validate, sync, find-missing, Excel\nI/O, and framework detection.\n\nV2 (current) adds:\n\n- AI-assisted translation (`langsync translate`) with pluggable providers\n  (OpenAI and DeepL released; Anthropic and Gemini behind an experimental flag).\n- Watch mode and incremental sync (`langsync watch`).\n- A reusable composite GitHub Action for `validate` and `find-missing`.\n- A VS Code extension with in-editor diagnostics and command-palette workflows.\n\nFuture releases will explore:\n\n- A web dashboard for translator collaboration.\n\n---\n\n## Contributing\n\nIssues and pull requests are welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md)\nfor development setup, testing conventions, and the commit-message policy.\n\n---\n\n## License\n\n[MIT](./LICENSE) © Mario Kreitz\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmariokreitz%2Flangsync","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmariokreitz%2Flangsync","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmariokreitz%2Flangsync/lists"}