@gusnips/vite 0.8.15 → 0.8.17

package/README.md

@@ -178,6 +178,82 @@ The script runs on its own, before your bundle, so it must not use anything outs
 tag goes at the end of `<head>` by default. `position: "head-prepend"` puts it first instead, so
 it does not wait for your stylesheets to download. Use that for a script that may leave the page.
 
+## Check your translations
+
+```ts
+// scripts/check-i18n.ts
+import { readFile } from "node:fs/promises";
+import { checkI18n, formatI18nReport, type I18nBundle } from "@gusnips/vite/i18n";
+
+const web: I18nBundle = {
+  name: "web",
+  locales: ["en", "pt-BR", "es"],
+  canonical: "en",
+  load: async (locale) => ({
+    translation: JSON.parse(await readFile(`src/i18n/locales/${locale}.json`, "utf8")),
+  }),
+};
+
+const report = await checkI18n([web]);
+
+console.log(formatI18nReport(report));
+process.exit(report.problems.some((p) => p.level === "error") ? 1 : 0);
+```
+
+Your `canonical` language is typed, so a `t("key")` it lacks already fails to compile. The other
+languages are not, and neither is anything inside a string. This checks what the compiler can't:
+
+| It fails when                                                  | Because the reader gets                               |
+| -------------------------------------------------------------- | ----------------------------------------------------- |
+| a key is in one language and not another, or is blank          | the canonical language, in the middle of their own    |
+| a counted key lacks a form its language needs (pt `_many`)     | English for exactly 1,000,000 of something            |
+| `{{name}}` became `{{nome}}`, or `{{n, number}}` lost `number` | a gap, or 5000 where they write 5.000                 |
+| `<0>…</0>` is out of order or not closed                       | the wrong words bold, or the tag as text              |
+| a placeholder is named `lng`, `ns` or another `t()` option     | another language, not the value                       |
+| a language fails to load                                       | nothing — every other rule would have passed it empty |
+
+`load` returns one language's catalogs by namespace, so JSON files, TS modules and a runtime
+merge all fit. If it throws, the check fails with the error. It never skips.
+
+Give it `code` and it reads your source too: every static `t("key")` exists, a template key's
+fixed start exists (``t(`plan.${id}.title`)`` needs `plan`), `<Trans>` has no children (they
+shift every `<0>`), and copy with `<strong>` in it is not read through `t()`, which prints the
+tag as text.
+
+```ts
+await checkI18n([{ ...web, code: ["src/**/*.{ts,tsx}"] }]);
+```
+
+Keys the server sends are shown in whatever language the reader has, so each one must be in every
+language. Pass the list if you can import it, or the server's source to scan for `messageKey:`:
+
+```ts
+await checkI18n([{ ...web, serverKeys: MESSAGE_KEYS }]);
+// or, with no list to import:
+await checkI18n([
+  { ...web, serverCode: ["apps/api/src/**/*.ts"], serverKeyPrefixes: ["serverErrors."] },
+]);
+```
+
+`report.unused` lists canonical keys no code seems to reach. It is a hint, not a failure: a key
+built at runtime from a variable can't be seen by a scan.
+
+If your prices come from a formatter, pass `{ price: /\$\s?\d/ }` as the second argument and a
+price typed into copy fails too.
+
+**Fragments.** If several people write screens at once, keep one file per area with every
+language side by side — `{ "en": {…}, "pt-BR": {…} }` — and merge them. `writeFragments` writes
+`out/<locale>.json` with sorted keys, so two runs write the same bytes, and writes nothing if two
+fragments disagree. The check then fails if a committed catalog no longer matches its fragments:
+
+```ts
+await checkI18n([{ ...web, fragments: { dir: "src/i18n/fragments", out: "src/i18n/locales" } }]);
+```
+
+If the app merges fragments at runtime with a spread (`{ ...auth.en, ...nav.en }`), leave `out`
+off and set `ownTopLevel: true`. A spread keeps only the second of two fragments that share a
+top-level key, so that is refused.
+
 ## The vite preset
 
 ```ts

package/dist/i18n.d.ts

@@ -0,0 +1,111 @@
+/** One i18next namespace's catalog: nested objects with strings at the leaves. */
+export type Catalog = object;
+/** One language's catalogs, by namespace: `{ translation: {…} }`. */
+export type Catalogs = Readonly<Record<string, Catalog>>;
+export interface I18nBundle {
+    /** Shown beside every problem: `"apps/web"`. */
+    name: string;
+    locales: readonly string[];
+    /** The app's `fallbackLng`: the language the others are compared to, and code keys must be in. */
+    canonical: string;
+    /**
+     * One language's catalogs. A throw fails the check with its message — it never skips the bundle,
+     * because every other rule compares languages and a missing one would pass them all.
+     */
+    load: (locale: string) => Catalogs | Promise<Catalogs>;
+    /** Copy kept as fragments, one area per file: see `mergeFragments`. Paths are relative to `root`. */
+    fragments?: FragmentsCheck;
+    /** Source that calls `t()`, as globs relative to `root`. Tests and `i18n/` folders are skipped. */
+    code?: readonly string[];
+    /** Every key the server can send, imported from where it is declared. Preferred over a scan. */
+    serverKeys?: readonly string[];
+    /** Server source to scan for `messageKey: "…"` when there is no list to import. */
+    serverCode?: readonly string[];
+    /** String literals in `serverCode` starting with one of these are keys too: `["serverErrors."]`. */
+    serverKeyPrefixes?: readonly string[];
+    /** Placeholders the app fills before i18next sees the string, so they may use a reserved name. */
+    brandVars?: Readonly<Record<string, string>>;
+    /** The namespace a `t()` bound to nothing reads. Default `"translation"`. */
+    defaultNamespace?: string;
+}
+export interface FragmentsCheck {
+    dir: string;
+    /**
+     * Where the merged catalogs are written, for an app that commits them. `out/<locale>.json` must
+     * then equal a fresh merge, so a hand edit or a fragment saved without re-merging fails. Leave it
+     * out when the app merges at runtime.
+     */
+    out?: string;
+    /** Refuse two fragments that share a top-level key: see `MergeOptions`. */
+    ownTopLevel?: boolean;
+}
+export interface CheckI18nOptions {
+    /** What `code`, `serverCode` and `fragments` are relative to. Default: the working directory. */
+    root?: string;
+    /**
+     * Refuse a price typed into copy, for a product whose prices come from a formatter. Off by
+     * default: most copy that matches is an example, not a price.
+     */
+    price?: RegExp;
+}
+export type I18nRule = "load" | "fragments" | "parity" | "plural" | "placeholders" | "reserved" | "tags" | "price" | "missing-key" | "dynamic-key" | "trans-children" | "markup" | "server-key";
+export interface I18nProblem {
+    rule: I18nRule;
+    /** A warning is shown and does not fail the gate. */
+    level: "error" | "warning";
+    bundle: string;
+    locale?: string;
+    key?: string;
+    /** `file:line`, for a problem found in code. */
+    at?: string;
+    message: string;
+}
+export interface I18nReport {
+    problems: I18nProblem[];
+    /** Canonical keys no static reference, template prefix or key-path literal reaches. Advisory. */
+    unused: {
+        bundle: string;
+        key: string;
+    }[];
+}
+export interface MergeOptions {
+    /**
+     * Refuse two fragments that share a top-level key. Set it when the app merges fragments at
+     * runtime with a spread — `{ ...auth.en, ...nav.en }` — where the second `nav` replaces the
+     * first instead of joining it, and the keys of one fragment vanish with no error anywhere.
+     */
+    ownTopLevel?: boolean;
+}
+export interface MergedFragments {
+    /** The text each `<locale>.json` must hold: keys sorted, two-space indent, a final newline. */
+    files: Map<string, string>;
+    /** A fragment that does not parse, or two that disagree. When not empty, nothing may be written. */
+    errors: string[];
+}
+/**
+ * Fold `dir/*.json` — one file per area, every language side by side, `{ "en": {…}, "pt-BR": {…} }`
+ * — into one catalog per language. Fragments exist so that people and agents building screens in
+ * parallel do not all edit the same three files. Deterministic: files in name order, keys sorted,
+ * so two runs write the same bytes and a derived catalog can be compared with a fresh merge.
+ */
+export declare function mergeFragments(dir: string, locales: readonly string[], options?: MergeOptions): Promise<MergedFragments>;
+/** Merge `dir` and write `out/<locale>.json`. Writes nothing when a fragment is broken, so a
+ *  catalog is never missing the half that failed to parse. Returns the errors. */
+export declare function writeFragments(dir: string, out: string, locales: readonly string[], options?: MergeOptions): Promise<string[]>;
+/**
+ * Run every rule over every bundle. Returns what it found rather than printing or exiting, so a repo
+ * can add checks of its own to the same report and decide how CI fails:
+ *
+ * ```ts
+ * const report = await checkI18n([web, site]);
+ * console.log(formatI18nReport(report));
+ * process.exit(report.problems.some((p) => p.level === "error") ? 1 : 0);
+ * ```
+ */
+export declare function checkI18n(bundles: readonly I18nBundle[], options?: CheckI18nOptions): Promise<I18nReport>;
+/** The report as lines for a terminal: one per problem, grouped by bundle, and a last line that
+ *  says whether the gate passed. Pass `showUnused` to list the advisory keys, not just count them. */
+export declare function formatI18nReport(report: I18nReport, options?: {
+    showUnused?: boolean;
+}): string;
+//# sourceMappingURL=i18n.d.ts.map

package/dist/i18n.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i18n.d.ts","sourceRoot":"","sources":["../src/i18n.ts"],"names":[],"mappings":"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"}