@mmstack/translate-tools 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present Miha J. Mulec
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,146 @@
+# @mmstack/translate-tools
+
+Build-time tooling for [`@mmstack/translate`](https://www.npmjs.com/package/@mmstack/translate): export your TypeScript-authored
+namespaces to JSON for translators / TMS platforms, then import the translations back as generated
+`createTranslation` modules.
+
+Authoring stays TypeScript-first, you keep writing `createNamespace({ ... })`. This tool just round-trips the **translations** through plain JSON files and writes the per-locale TypeScript for you, wiring each new locale into its `registerNamespace` registry. Allowing for easier co-working with translation teams or sharing between projects.
+
+It's a standalone CLI (+ a programmatic API), works in an Nx monorepo or a plain `ng new` app.
+
+## Install
+
+```bash
+npm i -D @mmstack/translate-tools
+# or: pnpm add -D @mmstack/translate-tools
+```
+
+## Compatibility
+
+This package is **versioned independently** (starting at `1.x`) rather than tracking Angular like the
+other `@mmstack/*` libraries. it's a Node tool that knows mmstack's _authoring patterns_, not
+Angular. It **never imports `@mmstack/translate`**; it statically reads your `createNamespace` /
+`registerNamespace` / `createTranslation` source, so a single version works across all current
+`@mmstack/translate` releases (v19+). A version-compatibility table will be added here only if the
+authoring API ever diverges.
+
+## The workflow
+
+```bash
+# 1. Hand off source strings to translators / your TMS
+npx mmtranslate export --src "src/**/*.ts" --out i18n
+
+# 2. ...they translate i18n/<namespace>.<locale>.json...
+
+# 3. Bring the translations back as generated TypeScript
+npx mmtranslate import --src "src/**/*.ts" --in i18n
+```
+
+## Commands
+
+### `export`
+
+Writes one **nested** JSON file per namespace per locale `<namespace>.<locale>.json` for the
+source locale and every registered target locale. Keys mirror your `createNamespace` tree; ICU
+messages are preserved verbatim.
+
+```bash
+npx mmtranslate export --src "src/**/*.ts" --out i18n --source-locale en
+```
+
+```jsonc
+// i18n/quote.en.json
+{
+  "title": "Quotes",
+  "detail": { "authorLabel": "Author" },
+}
+```
+
+It also writes a small hidden `.mmtranslate-meta.json` recording the source locale, so a later `import` knows which locale is the source even without `--source-locale`. It's not a translation file translators/TMS platforms can ignore it.
+
+### `import`
+
+For each `<namespace>.<locale>.json` that isn't the source locale, it:
+
+- **validates** every leaf is valid ICU, uses the **same placeholders** as the source (a dropped or
+  renamed `{name}` is reported), **covers every source key** (a missing key is reported), and
+  **contains no unknown keys** (an extra key would generate TypeScript that doesn't compile —
+  `createTranslation` is typed to the source shape). A file with any issue is rejected so nothing
+  "malformed" is written — always **per file**, so one bad file never blocks the rest of the run;
+- for a **new** locale, generates `<namespace>.<locale>.ts` (a `createTranslation` call) next to the
+  source namespace and inserts its loader into the matching `registerNamespace(...)` call. If a file
+  already exists at that path the locale is **rejected** unless you pass `--force`;
+- for an **existing** locale, updates that module's translation in place.
+
+`.json` files the run doesn't recognize — a typo'd namespace, a stray-dot name — are reported as
+**skipped** with a reason, so a mis-named file can't silently vanish from a run.
+
+`import` reads the source locale from the sidecar `export` wrote, so `--source-locale` only needs to
+be repeated if you're importing files that weren't produced by this tool.
+
+The source `createNamespace` is never regenerated.
+
+```bash
+npx mmtranslate import --src "src/**/*.ts" --in i18n --source-locale en
+```
+
+### `generate-manifest`
+
+Writes a config listing the discovered namespaces, their registry files, and locales. It's a starting point you can hand-edit if you'd rather pin discovery than rely on the automatic glob, or if that's not grabbing things correctly for some reason.
+
+```bash
+npx mmtranslate generate-manifest --src "src/**/*.ts" --out mmtranslate.config.ts
+```
+
+### Options
+
+| Flag                       | Applies to                 | Default                                     | Meaning                                                                |
+| -------------------------- | -------------------------- | ------------------------------------------- | ---------------------------------------------------------------------- |
+| `--src <glob>`             | all (repeatable)           | `src/**/*.ts`                               | Source files to scan.                                                  |
+| `--out <dir\|file>`        | export / generate-manifest | `translations` / `mmtranslate.config.ts`    | Output dir (export) or manifest file.                                  |
+| `--in <dir>`               | import                     | `translations`                              | Directory of translated JSON.                                          |
+| `--source-locale <locale>` | all                        | `en` (import: the value recorded at export) | Label for the default/source translation (your app's `defaultLocale`). |
+| `--force`                  | import                     | off                                         | Overwrite an existing file when adding a new locale.                   |
+
+## How discovery works
+
+The tool statically reads your `registerNamespace(default, { locale: loader })` calls, these are
+the per-namespace registries and resolves each loader to the `createNamespace`,
+`createMergedNamespace`, or `createTranslation` call it points at, lifting the translation object
+directly from source. No code runs.
+
+- **`withParams(...)`** is handled transparently: it's exported as its full ICU string, and target
+  locales are emitted as plain strings (they never need to repeat the wrapper).
+- **Merged namespaces** (`common.createMergedNamespace('quote', ...)`) export only their own keys —
+  the shared/common namespace is its own file, with no duplication.
+- **`registerRemoteNamespace`** or any imperative additions to translations are skipped.
+
+## Programmatic API
+
+The engine is exported too, if you'd rather script it:
+
+```ts
+import { Project } from 'ts-morph';
+import {
+  discoverFromProject,
+  planExport,
+  runImport,
+} from '@mmstack/translate-tools';
+```
+
+`runExport` / `runImport` / `runGenerateManifest` (fs-performing), plus the building blocks:
+`discoverFromProject`, `planExport`, `validateImport`, `applyImport`, and the lower-level
+`lift` / `codegen` / `registry` / `nested` / `icu` helpers.
+
+## Supported source shapes
+
+For a namespace to be discovered and round-tripped:
+
+- Loaders use a static dynamic `import('./path')`. Every form `@mmstack/translate` accepts at
+  runtime is supported: `.then((m) => m.quote.translation)`, `.then((m) => m.default)`, and the
+  `() => import('./path')` shorthand (which auto-resolves the module's `default` or `translation`
+  export). Async/`await` or computed-access loaders are skipped with a warning.
+- Translation values are string literals, template literals (no substitutions),
+  `withParams('literal')`, or nested objects. Dynamic values (a variable, a concatenation) are
+  rejected with a clear error — inline a literal so the tool can round-trip it.
+- A namespace name contains no `.` (it's the first segment of the export file name).

package/cli.d.mts

@@ -0,0 +1 @@
+export { };

package/cli.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+import { a as runGenerateManifest, i as runExport, o as runImport } from "./commands-yoWN-Tne.mjs";
+import * as path from "node:path";
+//#region src/lib/args.ts
+/** Minimal argv option readers shared by the CLI. Both guard against a missing value so a typo
+* (`--out --in i18n`) throws instead of silently swallowing the next flag as the option's value. */
+/** Read a `--name value` option; throws if the value is missing or is itself a flag. Returns
+* undefined when the option is absent. */
+function flag(args, name) {
+	const i = args.indexOf(`--${name}`);
+	if (i < 0) return void 0;
+	const value = args[i + 1];
+	if (value === void 0 || value.startsWith("--")) throw new Error(`Missing value for --${name}`);
+	return value;
+}
+/** Read a repeatable `--name value` option into an array; throws on any missing value. */
+function multiFlag(args, name) {
+	const out = [];
+	for (let i = 0; i < args.length; i++) {
+		if (args[i] !== `--${name}`) continue;
+		const value = args[i + 1];
+		if (value === void 0 || value.startsWith("--")) throw new Error(`Missing value for --${name}`);
+		out.push(value);
+		i += 1;
+	}
+	return out;
+}
+//#endregion
+//#region src/cli.ts
+const USAGE = `Usage: mmtranslate <command> [options]
+
+Commands:
+  export              Write nested JSON per namespace per locale (source + targets).
+  import              Read translated JSON back into TypeScript createTranslation files,
+                      registering any new locales.
+  generate-manifest   Write a config listing the discovered namespaces/registries.
+
+Options:
+  --src <glob>        Source glob to scan (repeatable). Default: src/**/*.ts
+  --out <dir|file>    Output dir (export) or manifest file (generate-manifest).
+  --in <dir>          Input dir of translated JSON (import).
+  --source-locale <l> Locale label for the default/source translation. Default: en
+                      (import falls back to the value recorded at export time).
+  --force             import: overwrite an existing file when adding a new locale.
+`;
+function main() {
+	const [, , command, ...rest] = process.argv;
+	const cwd = process.cwd();
+	const srcGlobsArg = multiFlag(rest, "src");
+	const srcGlobs = srcGlobsArg.length ? srcGlobsArg : ["src/**/*.ts"];
+	const sourceLocale = flag(rest, "source-locale");
+	if (command === "export") {
+		const outDir = path.resolve(cwd, flag(rest, "out") ?? "translations");
+		const files = runExport({
+			cwd,
+			srcGlobs,
+			outDir,
+			sourceLocale
+		});
+		console.log(`Exported ${files.length} file(s) to ${outDir}`);
+		return;
+	}
+	if (command === "import") {
+		const report = runImport({
+			cwd,
+			srcGlobs,
+			inDir: path.resolve(cwd, flag(rest, "in") ?? "translations"),
+			sourceLocale,
+			force: rest.includes("--force")
+		});
+		for (const { file, reason } of report.skipped) console.warn(`⚠ skipped ${file}: ${reason}`);
+		for (const { file, issues } of report.rejected) {
+			console.error(`✗ ${file}`);
+			for (const issue of issues) console.error(`   ${issue.key}: ${issue.message}`);
+		}
+		console.log(`Imported ${report.applied} locale file(s).`);
+		if (report.rejected.length) process.exitCode = 1;
+		return;
+	}
+	if (command === "generate-manifest") {
+		const outFile = path.resolve(cwd, flag(rest, "out") ?? "mmtranslate.config.ts");
+		runGenerateManifest({
+			cwd,
+			srcGlobs,
+			outFile,
+			sourceLocale
+		});
+		console.log(`Wrote manifest to ${outFile}`);
+		return;
+	}
+	console.error(USAGE);
+	process.exitCode = command ? 1 : 0;
+}
+try {
+	main();
+} catch (e) {
+	console.error(e instanceof Error ? e.message : String(e));
+	process.exitCode = 1;
+}
+//#endregion
+export {};
+
+//# sourceMappingURL=cli.mjs.map

package/cli.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.mjs","names":[],"sources":["../../../packages/translate-tools/src/lib/args.ts","../../../packages/translate-tools/src/cli.ts"],"sourcesContent":["/** Minimal argv option readers shared by the CLI. Both guard against a missing value so a typo\n * (`--out --in i18n`) throws instead of silently swallowing the next flag as the option's value. */\n\n/** Read a `--name value` option; throws if the value is missing or is itself a flag. Returns\n * undefined when the option is absent. */\nexport function flag(args: string[], name: string): string | undefined {\n  const i = args.indexOf(`--${name}`);\n  if (i < 0) return undefined;\n  const value = args[i + 1];\n  if (value === undefined || value.startsWith('--'))\n    throw new Error(`Missing value for --${name}`);\n  return value;\n}\n\n/** Read a repeatable `--name value` option into an array; throws on any missing value. */\nexport function multiFlag(args: string[], name: string): string[] {\n  const out: string[] = [];\n  for (let i = 0; i < args.length; i++) {\n    if (args[i] !== `--${name}`) continue;\n    const value = args[i + 1];\n    if (value === undefined || value.startsWith('--'))\n      throw new Error(`Missing value for --${name}`);\n    out.push(value);\n    i += 1;\n  }\n  return out;\n}\n","#!/usr/bin/env node\nimport * as path from 'node:path';\nimport { flag, multiFlag } from './lib/args';\nimport {\n  runExport,\n  runGenerateManifest,\n  runImport,\n} from './lib/commands';\n\nconst USAGE = `Usage: mmtranslate <command> [options]\n\nCommands:\n  export              Write nested JSON per namespace per locale (source + targets).\n  import              Read translated JSON back into TypeScript createTranslation files,\n                      registering any new locales.\n  generate-manifest   Write a config listing the discovered namespaces/registries.\n\nOptions:\n  --src <glob>        Source glob to scan (repeatable). Default: src/**/*.ts\n  --out <dir|file>    Output dir (export) or manifest file (generate-manifest).\n  --in <dir>          Input dir of translated JSON (import).\n  --source-locale <l> Locale label for the default/source translation. Default: en\n                      (import falls back to the value recorded at export time).\n  --force             import: overwrite an existing file when adding a new locale.\n`;\n\nfunction main(): void {\n  const [, , command, ...rest] = process.argv;\n  const cwd = process.cwd();\n  const srcGlobsArg = multiFlag(rest, 'src');\n  const srcGlobs = srcGlobsArg.length ? srcGlobsArg : ['src/**/*.ts'];\n  const sourceLocale = flag(rest, 'source-locale');\n\n  if (command === 'export') {\n    const outDir = path.resolve(cwd, flag(rest, 'out') ?? 'translations');\n    const files = runExport({ cwd, srcGlobs, outDir, sourceLocale });\n    console.log(`Exported ${files.length} file(s) to ${outDir}`);\n    return;\n  }\n\n  if (command === 'import') {\n    const inDir = path.resolve(cwd, flag(rest, 'in') ?? 'translations');\n    const force = rest.includes('--force');\n    const report = runImport({ cwd, srcGlobs, inDir, sourceLocale, force });\n    for (const { file, reason } of report.skipped)\n      console.warn(`⚠ skipped ${file}: ${reason}`);\n    for (const { file, issues } of report.rejected) {\n      console.error(`✗ ${file}`);\n      for (const issue of issues) console.error(`   ${issue.key}: ${issue.message}`);\n    }\n    console.log(`Imported ${report.applied} locale file(s).`);\n    if (report.rejected.length) process.exitCode = 1;\n    return;\n  }\n\n  if (command === 'generate-manifest') {\n    const outFile = path.resolve(cwd, flag(rest, 'out') ?? 'mmtranslate.config.ts');\n    runGenerateManifest({ cwd, srcGlobs, outFile, sourceLocale });\n    console.log(`Wrote manifest to ${outFile}`);\n    return;\n  }\n\n  console.error(USAGE);\n  process.exitCode = command ? 1 : 0;\n}\n\ntry {\n  main();\n} catch (e) {\n  console.error(e instanceof Error ? e.message : String(e));\n  process.exitCode = 1;\n}\n"],"mappings":";;;;;;;;AAKA,SAAgB,KAAK,MAAgB,MAAkC;CACrE,MAAM,IAAI,KAAK,QAAQ,KAAK,MAAM;CAClC,IAAI,IAAI,GAAG,OAAO,KAAA;CAClB,MAAM,QAAQ,KAAK,IAAI;CACvB,IAAI,UAAU,KAAA,KAAa,MAAM,WAAW,IAAI,GAC9C,MAAM,IAAI,MAAM,uBAAuB,MAAM;CAC/C,OAAO;AACT;;AAGA,SAAgB,UAAU,MAAgB,MAAwB;CAChE,MAAM,MAAgB,CAAC;CACvB,KAAK,IAAI,IAAI,GAAG,IAAI,KAAK,QAAQ,KAAK;EACpC,IAAI,KAAK,OAAO,KAAK,QAAQ;EAC7B,MAAM,QAAQ,KAAK,IAAI;EACvB,IAAI,UAAU,KAAA,KAAa,MAAM,WAAW,IAAI,GAC9C,MAAM,IAAI,MAAM,uBAAuB,MAAM;EAC/C,IAAI,KAAK,KAAK;EACd,KAAK;CACP;CACA,OAAO;AACT;;;ACjBA,MAAM,QAAQ;;;;;;;;;;;;;;;;AAiBd,SAAS,OAAa;CACpB,MAAM,KAAK,SAAS,GAAG,QAAQ,QAAQ;CACvC,MAAM,MAAM,QAAQ,IAAI;CACxB,MAAM,cAAc,UAAU,MAAM,KAAK;CACzC,MAAM,WAAW,YAAY,SAAS,cAAc,CAAC,aAAa;CAClE,MAAM,eAAe,KAAK,MAAM,eAAe;CAE/C,IAAI,YAAY,UAAU;EACxB,MAAM,SAAS,KAAK,QAAQ,KAAK,KAAK,MAAM,KAAK,KAAK,cAAc;EACpE,MAAM,QAAQ,UAAU;GAAE;GAAK;GAAU;GAAQ;EAAa,CAAC;EAC/D,QAAQ,IAAI,YAAY,MAAM,OAAO,cAAc,QAAQ;EAC3D;CACF;CAEA,IAAI,YAAY,UAAU;EAGxB,MAAM,SAAS,UAAU;GAAE;GAAK;GAAU,OAF5B,KAAK,QAAQ,KAAK,KAAK,MAAM,IAAI,KAAK,cAEN;GAAG;GAAc,OADjD,KAAK,SAAS,SACuC;EAAE,CAAC;EACtE,KAAK,MAAM,EAAE,MAAM,YAAY,OAAO,SACpC,QAAQ,KAAK,aAAa,KAAK,IAAI,QAAQ;EAC7C,KAAK,MAAM,EAAE,MAAM,YAAY,OAAO,UAAU;GAC9C,QAAQ,MAAM,KAAK,MAAM;GACzB,KAAK,MAAM,SAAS,QAAQ,QAAQ,MAAM,MAAM,MAAM,IAAI,IAAI,MAAM,SAAS;EAC/E;EACA,QAAQ,IAAI,YAAY,OAAO,QAAQ,iBAAiB;EACxD,IAAI,OAAO,SAAS,QAAQ,QAAQ,WAAW;EAC/C;CACF;CAEA,IAAI,YAAY,qBAAqB;EACnC,MAAM,UAAU,KAAK,QAAQ,KAAK,KAAK,MAAM,KAAK,KAAK,uBAAuB;EAC9E,oBAAoB;GAAE;GAAK;GAAU;GAAS;EAAa,CAAC;EAC5D,QAAQ,IAAI,qBAAqB,SAAS;EAC1C;CACF;CAEA,QAAQ,MAAM,KAAK;CACnB,QAAQ,WAAW,UAAU,IAAI;AACnC;AAEA,IAAI;CACF,KAAK;AACP,SAAS,GAAG;CACV,QAAQ,MAAM,aAAa,QAAQ,EAAE,UAAU,OAAO,CAAC,CAAC;CACxD,QAAQ,WAAW;AACrB"}