@moku-labs/game 0.2.0 → 0.3.0

package/README.md

@@ -42,6 +42,8 @@ You write small nodes and edge tables. The engine runs them, saves on the edges
 | V5 | Particles, WGSL filters, sprite frames, the production asset pack, a text field, visual tests. |
 | V6 | `platform`: Back button, haptics, keep-awake. Filters on WebGL. The game as a Tauri app on iOS and Android. |
 
+Strings are ICU messages with durations, translator notes, a pseudo-locale, and export and import for translators.
+
 Rendering is WebGPU first, with Pixi's WebGL fallback. A device with neither gets an honest "unsupported device" screen.
 
 ## Install

package/dist/assets.d.mts

@@ -1,4 +1,4 @@
-import { l as Manifest } from "./types-C47fKNcn.mjs";
+import { l as Manifest } from "./types-Dy1xB68L.mjs";
 
 //#region src/plugins/assets/scan/cli.d.ts
 /**
@@ -18,40 +18,103 @@ type StringsReport = {
   notes: readonly string[];
 };
 /**
- * Compiles the feature strings of a root into a folder, or checks them in a check run.
- * `compileStrings` of i18n fits it, and a test passes a stub instead.
+ * Compiles the feature strings of a root into a folder, or checks them in a check run; with
+ * `pseudo` it writes the pseudo-locale `en-XA` too. `compileStrings` of i18n fits it, and a test
+ * passes a stub instead.
+ *
+ * @example
+ * ```ts
+ * // A test of a wrapper script: a game with one English key.
+ * const compile: StringsCompiler = async () => ({ changed: false, locales: ["en"], keys: ["hud.title"], notes: [] });
+ * ```
  */
 type StringsCompiler = (root: string, out: string, options: {
   check: boolean;
+  pseudo: boolean;
 }) => Promise<StringsReport>;
+/**
+ * Writes one exchange file per locale for the translators into a folder, and reports how many
+ * keys each locale lacks. `exportStrings` of i18n fits it, and a test passes a stub instead.
+ *
+ * @example
+ * ```ts
+ * // A test of a wrapper script: two locales, Russian three keys short.
+ * const exportStub: StringsExporter = async () => ({ locales: ["en", "ru"], missing: { en: 0, ru: 3 } });
+ * ```
+ */
+type StringsExporter = (root: string, dir: string, options: {
+  source: string;
+}) => Promise<{
+  locales: readonly string[];
+  missing: Readonly<Record<string, number>>;
+}>;
+/**
+ * Takes the translated exchange files of a folder back into the string files of the features,
+ * then compiles into `out`. It reports the totals of the run: the locales read, the keys written
+ * and the feature files rewritten. `importStrings` of i18n fits it, and a test passes a stub.
+ *
+ * @example
+ * ```ts
+ * // A test of a wrapper script: the Russian file brought two hud texts.
+ * const importStub: StringsImporter = async () => ({ locales: ["ru"], keys: 2, files: ["features/hud/strings/ru.json"] });
+ * ```
+ */
+type StringsImporter = (root: string, dir: string, options: {
+  source: string;
+  pseudo: boolean;
+  out: string;
+}) => Promise<{
+  locales: readonly string[];
+  keys: number;
+  files: readonly string[];
+}>;
+/**
+ * The string tools of i18n the command line runs: the compile of every dev and pack run, the
+ * export of `--export` and the import of `--import`. The door `src/assets.ts` passes the real
+ * three.
+ *
+ * @example
+ * ```ts
+ * // src/assets.ts hands the i18n tools to the command line.
+ * const strings: StringsTools = { compile: compileStrings, exportStrings, importStrings };
+ * await runCli(["--root", "src", "--export", "translations"], strings); // 0
+ * ```
+ */
+type StringsTools = {
+  compile: StringsCompiler;
+  exportStrings: StringsExporter;
+  importStrings: StringsImporter;
+};
 /**
  * Runs the asset key scanner: walk the features, write the manifest and the key module, then
  * compile the feature strings next to the key module, or check that all of it is current. With
- * `--pack <dir>` it packs the art for production on the same scan (`--no-cache` for a cold run).
- * Nothing here calls `process.exit`; the caller does.
+ * `--pack <dir>` it packs the art for production on the same scan (`--no-cache` for a cold run);
+ * `--pseudo` adds the pseudo-locale to a dev run. `--export <dir>` and `--import <dir>` exchange
+ * the strings with translators and run alone, from the locale of `--source`. Nothing here calls
+ * `process.exit`; the caller does.
  *
  * @param argv - The arguments after the script name.
- * @param compile - The strings compiler, `compileStrings` of i18n.
+ * @param strings - The string tools of i18n: compile, export and import.
  * @param ui - Where the lines go. The branded console by default.
- * @returns The exit code: `1` when the scan, the compile or the pack failed or `--check` found a
- *   difference, else `0`.
+ * @returns The exit code: `1` when the flags, the scan, the compile, the pack, the export or the
+ *   import failed or `--check` found a difference, else `0`.
  * @example
  * ```ts
- * await runCli(["--root", "src", "--manifest", "public/assets/manifest.json", "--check"], compileStrings);
- * // 1 when public/assets/manifest.json is older than the files in src/features
- *
- * await runCli(["--root", "src", "--keys", "src/generated/assets.ts", "--pack", "dist/assets"], compileStrings);
+ * const strings = { compile: compileStrings, exportStrings, importStrings };
+ * await runCli(["--root", "src", "--keys", "src/generated/assets.ts", "--pack", "dist/assets"], strings);
  * // 0, and dist/assets holds the pages, the loose files and the packed manifest.json
+ * await runCli(["--root", "src", "--export", "translations"], strings);
+ * // 0, and translations/ holds one <locale>.json per locale for the translators
  * ```
  */
-declare function runCli(argv: string[], compile: StringsCompiler, ui?: ScanUi): Promise<number>;
+declare function runCli(argv: string[], strings: StringsTools, ui?: ScanUi): Promise<number>;
 //#endregion
 //#region src/plugins/i18n/compile/compile.d.ts
 /**
  * What one compile produced.
  */
 type CompileReport = {
-  /** True when an output on disk differs from what the compile produced. */changed: boolean; /** Every locale a feature brought a file for, sorted. */
+  /** True when an output on disk differs from what the compile produced. */changed: boolean; /** Every locale a feature brought a file for, and `en-XA` with `pseudo`, sorted. */
   locales: readonly string[]; /** Every message key, sorted. */
   keys: readonly string[]; /** One line per key a locale lacks. Nothing here stops a build. */
   notes: readonly string[];
@@ -61,22 +124,27 @@ type CompileReport = {
  */
 type CompileOptions = {
   /** True for a check run: nothing is written. */check?: boolean; /** Name of the folder that holds the features. Default `"features"`. */
-  features?: string;
+  features?: string; /** True to also write `strings.en-XA.ts`, the pseudo-locale, from the `"en"` messages. */
+  pseudo?: boolean;
 };
 /**
  * Walks `features/*​/strings/<locale>.json` of a game, compiles every message and writes the
- * generated modules: the types module `strings.ts` and one `strings.<locale>.ts` per locale. A
- * check run writes nothing and only reports whether something would change.
+ * generated modules: the types module `strings.ts` and one `strings.<locale>.ts` per locale, plus
+ * `strings.en-XA.ts` with `pseudo`. A check run writes nothing and only reports whether something
+ * would change; it checks `strings.en-XA.ts` only with `pseudo`.
  *
  * @param root - Game source root, the folder that holds the features.
  * @param out - The generated directory the modules are written into.
- * @param options - Whether this is a check run, and what the features folder is called.
+ * @param options - Whether this is a check run, what the features folder is called, and whether
+ *   the pseudo-locale is written.
  * @returns Whether an output differed, the locales, the keys and the notes.
- * @throws {Error} One error that lists every problem the compile found.
+ * @throws {Error} One error that lists every problem the compile found, or the pseudo error when
+ *   no feature brings an `en` string file.
  * @example
  * ```ts
- * const report = await compileStrings("src", "src/generated");
- * // report.locales: ["en", "ru"], report.changed: true on the first run
+ * // A dev build also writes the pseudo-locale, derived from the English messages.
+ * const report = await compileStrings("src", "src/generated", { pseudo: true });
+ * // report.locales: ["en", "en-XA", "ru"], report.changed: true on the first run
  * ```
  */
 declare function compileStrings(root: string, out: string, options?: CompileOptions): Promise<CompileReport>;
@@ -95,6 +163,97 @@ declare function compileStrings(root: string, out: string, options?: CompileOpti
  */
 declare function checkStrings(root: string, out: string): Promise<boolean>;
 //#endregion
+//#region src/plugins/i18n/compile/exchange.d.ts
+/**
+ * What an export and an import are told beyond their two paths.
+ *
+ * @example
+ * ```ts
+ * const options: ExchangeOptions = { source: "ru" }; // the translators read the Russian text
+ * ```
+ */
+type ExchangeOptions = {
+  /** The locale translators read from, written as `source` beside each text. Default `"en"`. */source?: string; /** Name of the folder that holds the features. Default `"features"`. */
+  features?: string;
+};
+/**
+ * What an import is told: the exchange options and the compile that runs after the files are
+ * written.
+ *
+ * @example
+ * ```ts
+ * const options: ImportOptions = { out: "src/generated", pseudo: true };
+ * ```
+ */
+type ImportOptions = ExchangeOptions & {
+  /** Where the compile after the import writes. Default `<root>/generated`. */out?: string; /** True to write the pseudo-locale `strings.en-XA.ts` in that compile too. */
+  pseudo?: boolean;
+};
+/**
+ * What an export wrote: the locales, one file each, and how many keys each one lacks.
+ *
+ * @example
+ * ```ts
+ * const report: ExportReport = { locales: ["en", "ru"], missing: { en: 0, ru: 3 } };
+ * ```
+ */
+type ExportReport = {
+  /** Every locale a file was written for, sorted. The source is one of them. */locales: readonly string[]; /** Per exported locale, how many keys had no text there. */
+  missing: Readonly<Record<string, number>>;
+};
+/**
+ * What an import wrote into the game.
+ *
+ * @example
+ * ```ts
+ * const report: ImportReport = { locales: ["ru"], keys: 3, files: ["features/hud/strings/ru.json"] };
+ * ```
+ */
+type ImportReport = {
+  /** Every locale an exchange file was read for, sorted. */locales: readonly string[]; /** How many keys were written. */
+  keys: number; /** The string files of the features that were rewritten, relative to the root, sorted. */
+  files: readonly string[];
+};
+/**
+ * Writes the files translators work in: one `<dir>/<locale>.json` per locale the features bring,
+ * the source locale included, so a new language starts as a copy of `en.json`. Every key of the
+ * game is in every file, sorted: `{ text, source, note? }`, with `text: ""` where the locale has no
+ * message yet. The game tree is not touched, and a second run writes the same bytes.
+ *
+ * @param root - Game source root, the folder that holds the features.
+ * @param dir - The folder the exchange files are written into; created when missing.
+ * @param options - The source locale and the name of the features folder.
+ * @returns The exported locales and how many keys each one lacks.
+ * @throws {Error} When the game's strings do not compile, or no feature brings the source locale.
+ * @example
+ * ```ts
+ * // Before a release, the game hands its strings to the translators.
+ * await exportStrings("src", "translations"); // { locales: ["en", "ru"], missing: { en: 0, ru: 3 } }
+ * // translations/ru.json: { "hud.bonus": { "text": "", "source": "Bonus" }, … }
+ * ```
+ */
+declare function exportStrings(root: string, dir: string, options?: ExchangeOptions): Promise<ExportReport>;
+/**
+ * Takes translated exchange files back into the game: every `<dir>/<locale>.json` is checked
+ * against the game first, then each new text is written into the string file of the feature that
+ * owns its key, and the strings are compiled into `out` as a dev run does. An empty text and a
+ * text equal to the current message are skipped. With any problem nothing is written.
+ *
+ * @param root - Game source root, the folder that holds the features.
+ * @param dir - The folder the translators handed back.
+ * @param options - The features folder, where the compile writes, and whether it writes `en-XA`.
+ * @returns The locales read, how many keys were written and the files rewritten.
+ * @throws {Error} One error that lists every problem of the exchange files, or the compile's own
+ *   error after the files are written (a parameter kind that differs across locales).
+ * @example
+ * ```ts
+ * // The translators handed back translations/ru.json with two hud texts filled in.
+ * await importStrings("src", "translations", { out: "src/generated" });
+ * // { locales: ["ru"], keys: 2, files: ["features/hud/strings/ru.json"] }
+ * ```
+ */
+declare function importStrings(root: string, dir: string, options?: ImportOptions): Promise<ImportReport>;
+//#endregion
 //#region src/plugins/assets/scan/emit.d.ts
 /**
  * Writes `manifest.json`: two-space JSON with a trailing newline, bundles sorted by name, pages
@@ -210,4 +369,4 @@ type ScanResult = {
  */
 declare function scanAssets(options: ScanOptions): Promise<ScanResult>;
 //#endregion
-export { type CompileOptions, type CompileReport, type PackOptions, type PackResult, type ScanOptions, type ScanResult, type ScanUi, type StringsCompiler, type StringsReport, checkStrings, compileStrings, emitKeys, emitManifest, packAssets, runCli, scanAssets };
+export { type CompileOptions, type CompileReport, type ExchangeOptions, type ExportReport, type ImportOptions, type ImportReport, type PackOptions, type PackResult, type ScanOptions, type ScanResult, type ScanUi, type StringsCompiler, type StringsExporter, type StringsImporter, type StringsReport, type StringsTools, checkStrings, compileStrings, emitKeys, emitManifest, exportStrings, importStrings, packAssets, runCli, scanAssets };