@babelize/engine 0.0.0-stage → 0.1.0

package/dist/providers/index.d.ts

@@ -0,0 +1,2 @@
+export * from './types';
+export { createDefaultTranslationProvider, toKeyResults } from './default-translation-provider';

package/dist/providers/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toKeyResults = exports.createDefaultTranslationProvider = void 0;
+__exportStar(require("./types"), exports);
+var default_translation_provider_1 = require("./default-translation-provider");
+Object.defineProperty(exports, "createDefaultTranslationProvider", { enumerable: true, get: function () { return default_translation_provider_1.createDefaultTranslationProvider; } });
+Object.defineProperty(exports, "toKeyResults", { enumerable: true, get: function () { return default_translation_provider_1.toKeyResults; } });

package/dist/providers/types.d.ts

@@ -0,0 +1,145 @@
+import type { TranslationEntry } from '../runtime/types';
+import type { MemoryEntry } from '../modules/translator/memory/types';
+import type { GlossaryEntryType } from '../modules/glossary/types';
+/**
+ * Everything the engine needs from the outside world, as interfaces. The
+ * engine never imports a database or cache client: the cloud backend injects
+ * Supabase/Redis-backed implementations, the CLI injects local ones (or none).
+ * A missing provider means the feature is off (no TM, no glossary, no cache).
+ */
+export type KeyFailureReason = 
+/** The provider's response had no entry for this key. */
+'missing_from_response'
+/** The provider returned an empty string for this key. */
+ | 'empty_value'
+/** A protected placeholder/tag/term was dropped, repeated or invented. */
+ | 'placeholder_lost'
+/** The output is the untranslated source sentence. */
+ | 'untranslated'
+/** An ICU message came back unparseable or with changed arguments/branches. */
+ | 'icu_invalid'
+/** HTML/JSX tags in the output don't match the source. */
+ | 'markup_mismatch'
+/** The provider can't handle this string (e.g. ICU or mixed scripts on NLLB). */
+ | 'unsupported_by_provider'
+/** The request for this key's batch failed (network, service error). */
+ | 'provider_error';
+/** Why a key has no translation in this run. Failed keys are retried next run. */
+export interface KeyFailure {
+    reason: KeyFailureReason;
+    retryable: boolean;
+    message?: string;
+}
+/** A key that has no translation for a locale in a run, and why. */
+export interface TranslationFailure extends KeyFailure {
+    locale: string;
+    key: string;
+    source: string;
+}
+/**
+ * Per-key outcome of a translation request. A provider must return exactly
+ * one result per requested key and never substitute the source text for a
+ * translation: a key it couldn't translate is a `failed` result, never a
+ * silent `ok`.
+ */
+export type KeyResult = {
+    key: string;
+    status: 'ok';
+    value: string;
+    confidence?: number;
+    engine?: string;
+    warnings?: string[];
+} | {
+    key: string;
+    status: 'failed';
+    reason: KeyFailureReason;
+    retryable: boolean;
+    message?: string;
+};
+export interface TranslationBatchRequest {
+    entries: TranslationEntry[];
+    /** FLORES-200 codes, e.g. eng_Latn */
+    sourceLang: string;
+    targetLang: string;
+    /** Brand voice to put in the prompt (LLM providers only). */
+    brandVoice?: string;
+    /** Target locale as an ISO code, e.g. "fr" or "pt-BR" (LLM providers only). */
+    targetLocale?: string;
+    /** Required terminology for this batch: source term → translation (LLM providers only). */
+    glossary?: Array<{
+        term: string;
+        translation: string;
+    }>;
+    /**
+     * Per-key notes for a repair attempt, e.g. which token the previous attempt
+     * dropped (LLM providers only).
+     */
+    hints?: Record<string, string>;
+}
+export interface TranslationBatchOptions {
+    /**
+     * Aborts the request, including any retries in progress (the caller's time
+     * budget ran out or its client went away). The promise then rejects.
+     */
+    signal?: AbortSignal;
+}
+export interface TranslationProvider {
+    /**
+     * Output is pseudo-localization (testing), not translation: it is marked
+     * in the lockfile and replaced by the next real run.
+     */
+    readonly pseudo?: boolean;
+    /**
+     * Translate a batch. Resolves with one KeyResult per requested entry.
+     * Rejects only when the request as a whole failed (network, auth, 5xx) or
+     * was aborted through `options.signal`.
+     */
+    translateBatch(request: TranslationBatchRequest, options?: TranslationBatchOptions): Promise<KeyResult[]>;
+}
+export interface TranslationMemoryContext {
+    ownerId: string | null;
+    projectName: string | null;
+}
+export interface TranslationMemoryStore {
+    /** Owner whose memory this project reads/writes, and the project's name. */
+    getProjectContext(projectId: string): Promise<TranslationMemoryContext>;
+    /** All entries for an owner and FLORES language pair. Throws on failure. */
+    getAllForOwner(ownerId: string, sourceLocale: string, targetLocale: string): Promise<MemoryEntry[]>;
+    /**
+     * Upsert entries. `overwrite: false` must leave existing entries untouched.
+     * Throws on failure.
+     */
+    saveBatch(ownerId: string, projectId: string, entries: MemoryEntry[], options?: {
+        overwrite?: boolean;
+    }): Promise<void>;
+}
+export interface GlossaryRule {
+    term: string;
+    type: GlossaryEntryType;
+    translations: Record<string, string> | null;
+}
+export interface ProjectRulesStore {
+    getGlossary(projectId: string): Promise<GlossaryRule[]>;
+    getBrandVoice(projectId: string): Promise<string | null>;
+}
+export interface TranslationCache {
+    get(key: string): Promise<{
+        hit: boolean;
+        data: string | null;
+    }>;
+    set(key: string, value: string, ttlSeconds: number): Promise<void>;
+}
+export interface EngineProviders {
+    translator?: TranslationProvider;
+    /**
+     * Second chance for keys the (LLM) translator failed with `provider_error`
+     * (rate limit, outage), tried once after the repair pass. Treated as a
+     * non-LLM service (e.g. NLLB): ICU and mixed-script keys are never sent to
+     * it, and its output isn't cached or written to translation memory. Keys it
+     * translated get `fallback: true` in their metadata.
+     */
+    fallbackTranslator?: TranslationProvider;
+    memory?: TranslationMemoryStore;
+    rules?: ProjectRulesStore;
+    cache?: TranslationCache;
+}

package/dist/providers/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/qa/check-project.d.ts

@@ -0,0 +1,49 @@
+import { type LocaleGlossary, type LocaleIssue, type LocalePairReport } from './locale-qa';
+import { type FindLocaleOptions, type LocaleFileSet } from './locale-files';
+export interface ProjectLocaleConfig {
+    sourceLocale?: string;
+    targetLocales?: string[];
+    glossary?: LocaleGlossary;
+}
+/**
+ * The parts of `.babelize/config.json` the local tools use. Missing or
+ * malformed config is not an error: everything in it is optional.
+ */
+export declare function readProjectLocaleConfig(projectDir: string): Promise<ProjectLocaleConfig>;
+export interface LocaleSetReport {
+    dir: string;
+    layout: LocaleFileSet['layout'];
+    sourceLocale: string;
+    /** Source keys checked against. */
+    sourceKeys: number;
+    locales: LocalePairReport[];
+    /** Locales asked for but without a file in this set. */
+    missingLocales: string[];
+    /** Unreadable/invalid locale files. */
+    fileErrors: Array<{
+        file: string;
+        message: string;
+    }>;
+}
+export interface ProjectLocaleCheck {
+    sourceLocale: string;
+    sets: LocaleSetReport[];
+    /** Sets found without a source locale file (cannot be checked). */
+    skippedSets: Array<{
+        dir: string;
+        locales: string[];
+    }>;
+}
+export interface CheckProjectOptions {
+    sourceLocale?: string;
+    /** Only these target locales (default: every locale file found). */
+    locales?: string[];
+    glossary?: LocaleGlossary;
+    /** Restrict each locale's checks to these keys (review of a diff). */
+    keys?: string[];
+    /** Directory names skipped when looking for locale files (default: deps, build output, tests, fixtures). */
+    ignoreDirs?: FindLocaleOptions['ignoreDirs'];
+}
+/** The file a locale issue lives in, relative to the project root. */
+export declare function localeIssueFile(set: Pick<LocaleSetReport, 'dir' | 'layout'>, issue: Pick<LocaleIssue, 'key' | 'locale'>): string;
+export declare function checkProjectLocales(projectDir: string, options?: CheckProjectOptions): Promise<ProjectLocaleCheck>;

package/dist/qa/check-project.js

@@ -0,0 +1,150 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readProjectLocaleConfig = readProjectLocaleConfig;
+exports.localeIssueFile = localeIssueFile;
+exports.checkProjectLocales = checkProjectLocales;
+/**
+ * QA every locale file set in a project against its source locale. Read-only,
+ * no network: see ./locale-qa for the checks.
+ */
+const fs_1 = require("fs");
+const path = __importStar(require("path"));
+const locale_qa_1 = require("./locale-qa");
+const locale_files_1 = require("./locale-files");
+/**
+ * The parts of `.babelize/config.json` the local tools use. Missing or
+ * malformed config is not an error: everything in it is optional.
+ */
+async function readProjectLocaleConfig(projectDir) {
+    let raw;
+    try {
+        raw = JSON.parse(await fs_1.promises.readFile(path.join(projectDir, '.babelize', 'config.json'), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+    if (!raw || typeof raw !== 'object')
+        return {};
+    const str = (v) => (typeof v === 'string' && (0, locale_files_1.isLocaleCode)(v) ? v : undefined);
+    const list = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === 'string' && (0, locale_files_1.isLocaleCode)(x)) : undefined);
+    const config = {
+        sourceLocale: str(raw.sourceLocale) ?? str(raw.source) ?? str(raw.sourceLanguage),
+        targetLocales: list(raw.targetLocales) ?? list(raw.targetLanguageIds) ?? list(raw.targetLanguages),
+    };
+    const g = raw.glossary;
+    if (g && typeof g === 'object') {
+        const neverTranslate = Array.isArray(g.neverTranslate) ? g.neverTranslate.filter((t) => typeof t === 'string') : [];
+        const alwaysTranslateAs = Array.isArray(g.alwaysTranslateAs)
+            ? g.alwaysTranslateAs.filter((e) => !!e && typeof e === 'object' && typeof e.term === 'string' &&
+                !!e.translations && typeof e.translations === 'object')
+            : [];
+        if (neverTranslate.length || alwaysTranslateAs.length)
+            config.glossary = { neverTranslate, alwaysTranslateAs };
+    }
+    return config;
+}
+/** The file a locale issue lives in, relative to the project root. */
+function localeIssueFile(set, issue) {
+    if (set.layout === 'namespaced') {
+        const ns = issue.key.includes(':') ? issue.key.split(':')[0] : 'translation';
+        return `${set.dir}/${issue.locale}/${ns}.json`;
+    }
+    return `${set.dir}/${issue.locale}.json`;
+}
+/** Pick the source locale: explicit, `.babelize/config.json`, `en`, or the only locale every set has. */
+function chooseSourceLocale(sets, explicit, configured) {
+    if (explicit)
+        return explicit;
+    if (configured)
+        return configured;
+    if (sets.some((s) => s.files.en))
+        return 'en';
+    const first = sets[0] && Object.keys(sets[0].files)[0];
+    return first ?? 'en';
+}
+/** Target locales from `.babelize/config.json` and the local lockfile (`.babelize/local/babelize-lock.json`). */
+async function expectedTargetLocales(projectDir, config) {
+    const found = new Set(config.targetLocales ?? []);
+    try {
+        const lock = JSON.parse(await fs_1.promises.readFile(path.join(projectDir, '.babelize', 'local', 'babelize-lock.json'), 'utf8'));
+        for (const entry of Object.values(lock.keys ?? {}))
+            for (const l of Object.keys(entry.languages ?? {}))
+                found.add(l);
+    }
+    catch {
+        // No lockfile: nothing translated locally yet.
+    }
+    return [...found].filter((l) => (0, locale_files_1.isLocaleCode)(l));
+}
+async function checkProjectLocales(projectDir, options = {}) {
+    const config = await readProjectLocaleConfig(projectDir);
+    // Locales the project is supposed to have: a configured or previously
+    // translated locale without a file is reported, not silently skipped.
+    const expected = options.locales?.length ? [] : await expectedTargetLocales(projectDir, config);
+    const sets = await (0, locale_files_1.findLocaleFileSets)(projectDir, { ignoreDirs: options.ignoreDirs });
+    const sourceLocale = chooseSourceLocale(sets, options.sourceLocale, config.sourceLocale);
+    const glossary = options.glossary ?? config.glossary;
+    const reports = [];
+    const skippedSets = [];
+    for (const set of sets) {
+        if (!set.files[sourceLocale]) {
+            skippedSets.push({ dir: set.dir, locales: Object.keys(set.files).sort() });
+            continue;
+        }
+        const source = await (0, locale_files_1.loadLocale)(projectDir, set, sourceLocale);
+        const available = Object.keys(set.files).filter((l) => l !== sourceLocale).sort();
+        const wanted = options.locales?.length
+            ? options.locales.filter((l) => l !== sourceLocale)
+            : [...new Set([...available, ...expected])].filter((l) => l !== sourceLocale).sort();
+        const fileErrors = [...source.errors];
+        const locales = [];
+        for (const locale of wanted.filter((l) => set.files[l])) {
+            const target = await (0, locale_files_1.loadLocale)(projectDir, set, locale);
+            fileErrors.push(...target.errors);
+            locales.push((0, locale_qa_1.checkLocalePair)(source.messages, target.messages, locale, { sourceLocale, glossary, keys: options.keys }));
+        }
+        reports.push({
+            dir: set.dir,
+            layout: set.layout,
+            sourceLocale,
+            sourceKeys: Object.keys(source.messages).length,
+            locales,
+            missingLocales: wanted.filter((l) => !set.files[l]),
+            fileErrors,
+        });
+    }
+    return { sourceLocale, sets: reports, skippedSets };
+}

package/dist/qa/locale-files.d.ts

@@ -0,0 +1,44 @@
+export interface LocaleFileSet {
+    /** Directory holding the set, relative to the project root (posix). */
+    dir: string;
+    layout: 'flat' | 'namespaced';
+    /** locale → files (relative to the project root, posix). */
+    files: Record<string, string[]>;
+}
+export interface LoadedLocale {
+    locale: string;
+    files: string[];
+    messages: Record<string, string>;
+    /** Files that could not be read or parsed, with the reason. */
+    errors: Array<{
+        file: string;
+        message: string;
+    }>;
+}
+/**
+ * Directories never searched for locale files: dependencies, build output,
+ * and test/fixture trees (whose locale files are test data, not the app's).
+ */
+export declare const DEFAULT_LOCALE_IGNORE_DIRS: readonly string[];
+export interface FindLocaleOptions {
+    /** Directory names to skip at any depth (default DEFAULT_LOCALE_IGNORE_DIRS). */
+    ignoreDirs?: readonly string[];
+}
+export declare function isLocaleCode(name: string): boolean;
+/** True when a relative path runs through an ignored directory. */
+export declare function isIgnoredLocalePath(rel: string, ignoreDirs?: readonly string[]): boolean;
+/**
+ * Group relative `.json` paths into locale file sets. Paths that aren't
+ * `<dir>/<locale>.json` or `<dir>/<locale>/<ns>.json` under a locale folder
+ * are ignored.
+ */
+export declare function groupLocaleFiles(paths: string[], options?: FindLocaleOptions): LocaleFileSet[];
+export declare function findLocaleFileSets(projectDir: string, options?: FindLocaleOptions): Promise<LocaleFileSet[]>;
+/** Reads a project file by relative path; null when it doesn't exist (in that version). */
+export type ProjectFileReader = (rel: string) => Promise<string | null>;
+/**
+ * Read and flatten one locale of a set. Namespaced files are keyed `ns:key`.
+ * `read` reads another version of the files (e.g. from git); by default the
+ * working tree is read.
+ */
+export declare function loadLocale(projectDir: string, set: LocaleFileSet, locale: string, read?: ProjectFileReader): Promise<LoadedLocale>;

package/dist/qa/locale-files.js

@@ -0,0 +1,159 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_LOCALE_IGNORE_DIRS = void 0;
+exports.isLocaleCode = isLocaleCode;
+exports.isIgnoredLocalePath = isIgnoredLocalePath;
+exports.groupLocaleFiles = groupLocaleFiles;
+exports.findLocaleFileSets = findLocaleFileSets;
+exports.loadLocale = loadLocale;
+/**
+ * Find a project's JSON locale files without running the pipeline (read-only).
+ *
+ * Recognised layouts, under any directory named locales/messages/lang(s)/
+ * i18n/translations (the engine itself writes `<publicDir>/locales/<locale>.json`):
+ *
+ *   locales/en.json, locales/fr.json            flat: one file per locale
+ *   locales/en/common.json, locales/fr/common.json   namespaced (i18next): keys become `common:key`
+ */
+const path = __importStar(require("path"));
+const fs_1 = require("fs");
+const fast_glob_1 = __importDefault(require("fast-glob"));
+const locale_qa_1 = require("./locale-qa");
+const LOCALE_DIR_NAMES = ['locales', 'locale', 'messages', 'lang', 'langs', 'i18n', 'translations'];
+/**
+ * Directories never searched for locale files: dependencies, build output,
+ * and test/fixture trees (whose locale files are test data, not the app's).
+ */
+exports.DEFAULT_LOCALE_IGNORE_DIRS = [
+    'node_modules', '.git', '.next', 'dist', 'build', 'coverage', '.babelize', 'out',
+    '__fixtures__', 'fixtures', '__tests__', '__mocks__', 'test', 'tests', 'testing', 'e2e',
+];
+/** en, fr, pt-BR, zh_Hant, sr-Latn-RS — a locale code, not a namespace like "common". */
+const LOCALE_CODE = /^[a-z]{2,3}(?:[-_](?:[A-Z][a-z]{3}|[A-Za-z]{2}|\d{3}))*$/;
+function isLocaleCode(name) {
+    return LOCALE_CODE.test(name);
+}
+function toPosix(p) {
+    return p.split(path.sep).join('/');
+}
+/** True when a relative path runs through an ignored directory. */
+function isIgnoredLocalePath(rel, ignoreDirs = exports.DEFAULT_LOCALE_IGNORE_DIRS) {
+    const dirs = rel.split('/').slice(0, -1);
+    return dirs.some((d) => ignoreDirs.includes(d));
+}
+/**
+ * Group relative `.json` paths into locale file sets. Paths that aren't
+ * `<dir>/<locale>.json` or `<dir>/<locale>/<ns>.json` under a locale folder
+ * are ignored.
+ */
+function groupLocaleFiles(paths, options = {}) {
+    var _a;
+    const ignoreDirs = options.ignoreDirs ?? exports.DEFAULT_LOCALE_IGNORE_DIRS;
+    const sets = new Map();
+    for (const rel of [...new Set(paths.map(toPosix))].sort()) {
+        if (!rel.endsWith('.json') || isIgnoredLocalePath(rel, ignoreDirs))
+            continue;
+        const parts = rel.split('/');
+        const file = parts[parts.length - 1];
+        const parent = parts[parts.length - 2];
+        let dir;
+        let locale;
+        let layout;
+        if (parent !== undefined && LOCALE_DIR_NAMES.includes(parent) && isLocaleCode(file.slice(0, -5))) {
+            dir = parts.slice(0, -1).join('/');
+            locale = file.slice(0, -5);
+            layout = 'flat';
+        }
+        else if (parts.length >= 3 && LOCALE_DIR_NAMES.includes(parts[parts.length - 3]) && isLocaleCode(parent)) {
+            dir = parts.slice(0, -2).join('/');
+            locale = parent;
+            layout = 'namespaced';
+        }
+        else {
+            continue;
+        }
+        const id = `${dir}\u0000${layout}`;
+        const set = sets.get(id) ?? { dir, layout, files: {} };
+        ((_a = set.files)[locale] ?? (_a[locale] = [])).push(rel);
+        sets.set(id, set);
+    }
+    return [...sets.values()];
+}
+async function findLocaleFileSets(projectDir, options = {}) {
+    const names = `{${LOCALE_DIR_NAMES.join(',')}}`;
+    const ignoreDirs = options.ignoreDirs ?? exports.DEFAULT_LOCALE_IGNORE_DIRS;
+    const found = await (0, fast_glob_1.default)([`**/${names}/*.json`, `**/${names}/*/*.json`], {
+        cwd: projectDir,
+        ignore: ignoreDirs.map((d) => `**/${d}/**`),
+        onlyFiles: true,
+        deep: 8,
+        followSymbolicLinks: false,
+    });
+    return groupLocaleFiles(found, options);
+}
+/**
+ * Read and flatten one locale of a set. Namespaced files are keyed `ns:key`.
+ * `read` reads another version of the files (e.g. from git); by default the
+ * working tree is read.
+ */
+async function loadLocale(projectDir, set, locale, read = (rel) => fs_1.promises.readFile(path.join(projectDir, rel), 'utf8').catch((err) => {
+    if (err.code === 'ENOENT')
+        return null;
+    throw err;
+})) {
+    const files = set.files[locale] ?? [];
+    const messages = {};
+    const errors = [];
+    for (const rel of files) {
+        try {
+            const content = await read(rel);
+            if (content === null)
+                continue;
+            const data = JSON.parse(content);
+            const flat = (0, locale_qa_1.flattenLocaleMessages)(data);
+            const ns = set.layout === 'namespaced' ? path.basename(rel, '.json') : null;
+            for (const [k, v] of Object.entries(flat))
+                messages[ns ? `${ns}:${k}` : k] = v;
+        }
+        catch (err) {
+            errors.push({ file: toPosix(rel), message: err instanceof SyntaxError ? `invalid JSON: ${err.message}` : err.message });
+        }
+    }
+    return { locale, files, messages, errors };
+}

package/dist/qa/locale-qa.d.ts

@@ -0,0 +1,61 @@
+export type LocaleIssueCode = 'missing_key' | 'extra_key' | 'empty_value' | 'untranslated' | 'placeholder_mismatch' | 'icu_invalid' | 'icu_mismatch' | 'plural_category_invalid' | 'plural_category_missing' | 'glossary_violation'
+/** The source text changed but the translation didn't (review of a diff). */
+ | 'stale_translation'
+/** A translation present at the base of a diff was deleted while the source still has it. */
+ | 'translation_removed'
+/** Pseudo-localized test output (`--provider pseudo`, ⟦…⟧), not a translation. */
+ | 'pseudo_translation';
+export type LocaleIssueSeverity = 'error' | 'warning' | 'info';
+export interface LocaleIssue {
+    locale: string;
+    key: string;
+    code: LocaleIssueCode;
+    severity: LocaleIssueSeverity;
+    /** What is wrong, in plain words. */
+    message: string;
+}
+export interface LocaleGlossary {
+    /** Terms that must appear unchanged in every translation (brand names, …). */
+    neverTranslate?: string[];
+    /** Terms with a fixed translation per locale. */
+    alwaysTranslateAs?: Array<{
+        term: string;
+        translations: Record<string, string>;
+    }>;
+}
+export interface LocalePairOptions {
+    /** Source locale code; values identical to the source aren't flagged for a locale of the same language. */
+    sourceLocale?: string;
+    glossary?: LocaleGlossary;
+    /**
+     * Only check these keys (e.g. the keys changed in a diff). Missing/extra
+     * detection is limited to them too.
+     */
+    keys?: string[];
+}
+export interface LocalePairReport {
+    locale: string;
+    /** Keys in the source locale (plural groups count once). */
+    total: number;
+    /** Source keys (or plural groups) with a non-empty value in the target. */
+    translated: number;
+    /** Issue count by code. */
+    counts: Partial<Record<LocaleIssueCode, number>>;
+    errors: number;
+    warnings: number;
+    issues: LocaleIssue[];
+}
+/**
+ * Flatten nested locale JSON into dotted keys with string values. The
+ * engine's `_meta` block is dropped; non-string leaves (numbers, arrays) are
+ * not messages and are skipped.
+ */
+export declare function flattenLocaleMessages(data: unknown, prefix?: string, out?: Record<string, string>): Record<string, string>;
+/**
+ * Check one target locale against the source locale. Both maps are flat
+ * (see {@link flattenLocaleMessages}). Issues come in key order, errors and
+ * warnings mixed; callers cap and sort as they need.
+ */
+export declare function checkLocalePair(source: Record<string, string>, target: Record<string, string>, locale: string, options?: LocalePairOptions): LocalePairReport;
+/** Recompute `counts`/`errors`/`warnings` from `issues` (after adding issues to a report). */
+export declare function tallyLocaleIssues(report: LocalePairReport): LocalePairReport;