https://github.com/softwarity/polyglot
https://github.com/softwarity/polyglot
Last synced: 5 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/softwarity/polyglot
- Owner: softwarity
- License: mit
- Created: 2026-06-01T12:52:49.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-06-01T13:21:08.000Z (about 1 month ago)
- Last Synced: 2026-06-01T14:26:09.795Z (about 1 month ago)
- Language: JavaScript
- Homepage: https://softwarity.github.io/polyglot/
- Size: 91.8 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# @softwarity/polyglot
[](https://www.npmjs.com/package/@softwarity/polyglot)
[](./LICENSE)
[](https://angular.dev/guide/i18n)
[](https://nodejs.org)
[](https://github.com/softwarity/polyglot/actions/workflows/ci.yml)
> Serve **every locale** of an Angular i18n app at once, behind a single dev port.
`ng serve` runs one locale at a time, so you never see the real multi-locale URL
shape in development. **polyglot** reads your `angular.json`, spawns one `ng serve`
per locale on a private port, and puts a single proxy in front — so `/en/`, `/fr/`,
`/vi/`… all work from one URL, exactly like the deployed site.
📖 **Documentation:** https://softwarity.github.io/polyglot/
## Install
```bash
npm i -D @softwarity/polyglot
```
## Quick start
```bash
# 1. Add a ready-to-run script to package.json (writes "start:i18n")
npx polyglot init
# 2. Run it — pick which locales to start
npm run start:i18n
```
`init` writes the defaults so you can see and tweak them:
```json
"scripts": {
"start:i18n": "polyglot --config=./angular.json --port=4200"
}
```
At launch, polyglot reads your locales and asks which to run (nothing is saved):
```text
Project: my-app — source locale: en — baseHref: /
Available locales:
1. en (source)
2. fr
3. vi
Which locales to run? Comma-separated numbers (e.g. "1,3"), "all" (default), or "q" to quit: all
▸ Proxy listening on 0.0.0.0:4200 — open one of:
Local: http://localhost:4200/
en → http://localhost:4200/en/ (ng serve :49b1)
fr → http://localhost:4200/fr/ (ng serve :49b2)
vi → http://localhost:4200/vi/ (ng serve :49b3)
▸ Fallback locale: en
```
## Commands & options
```bash
polyglot [options] # Start the multi-locale dev proxy (default)
polyglot init [options] # Add a "start:i18n" script to package.json
polyglot --help # Show usage
```
| Option | Default | Description |
| --- | --- | --- |
| `--config=` | `./angular.json` | Angular workspace config to read locales from |
| `--project=` | first project | Project to serve (multi-project workspaces) |
| `--port=` | `4200` (or `$PROXY_PORT`) | Public port for the proxy |
| `--help` | — | Print usage and exit |
There is intentionally **no** `--prebundle` flag and **no** locale flag: locales are
chosen interactively, and Vite prebundling is derived from your selection (off for
multiple locales, on for one — see below).
## How it works
- Reads `i18n`, `baseHref` and `serve` configs from `angular.json`.
- Picks a free **private** port per locale and spawns `ng serve --configuration=`
bound to `127.0.0.1`.
- Runs **one** Express proxy on the public port, routing each locale's `subPath`
(``) to its `ng serve` instance; any other path redirects to the source locale.
- Tears everything down on exit (`SIGTERM` → `SIGKILL`) — no orphan servers.
**Prebundling.** Angular's dev-server runs on Vite, which pre-bundles dependencies into
a shared `.angular/cache` directory. With several `ng serve` running at once, each
optimizer keeps invalidating the others (*"There is a new version of the pre-bundle…"*),
wedging SSR in a re-optimize loop. So polyglot disables prebundling automatically when
more than one locale runs, and keeps it on for a single locale.
## Requirements
A standard Angular i18n setup in `angular.json`:
- an `i18n` block with `sourceLocale` and `locales` (each may declare a `subPath`);
- a **build** configuration per locale with a matching `baseHref` (`"//"`);
- a **serve** configuration per locale (`ng serve --configuration=`).
See the [Angular setup guide](https://softwarity.github.io/polyglot/#/angular-setup).
## License
MIT © [Softwarity](https://www.softwarity.io/)