@katerynakhar/i18n-keeper 0.16.0

package/dist/memory.d.ts

@@ -0,0 +1,72 @@
+import type { Config } from './types.js';
+export declare const MEMORY_FILE = ".i18n/memory.json";
+export interface MemoryEntry {
+    /** Hash of the source string at the moment this translation was recorded. */
+    sourceHash: string;
+    value: string;
+    origin: 'human' | 'machine';
+    reviewed: boolean;
+    updatedAt: string;
+    /** When a person signed off on it, for entries that have been reviewed. */
+    reviewedAt?: string;
+}
+export interface Unreviewed {
+    locale: string;
+    key: string;
+    entry: MemoryEntry;
+}
+/** Everything still waiting for a person to look at it, in a stable order. */
+export declare function unreviewed(memory: Memory, locales?: string[], keys?: string[]): Unreviewed[];
+/**
+ * Signs off on translations a person has actually looked at.
+ *
+ * Nothing else in the tool can set this: a machine translation is recorded
+ * unreviewed and stays that way until someone says otherwise, which is the
+ * whole point of recording it.
+ */
+export declare function markReviewed(entries: Unreviewed[], now: string): number;
+export interface Memory {
+    version: 1;
+    sourceLocale: string;
+    /** locale -> key -> entry. Nested rather than a flat list, for readable diffs. */
+    entries: Record<string, Record<string, MemoryEntry>>;
+}
+export declare class MemoryError extends Error {
+}
+/** 48 bits is plenty to notice an edited string, and keeps the file readable. */
+export declare function hashValue(value: string): string;
+export declare function memoryPath(root: string, explicit?: string): string;
+export declare function emptyMemory(sourceLocale: string): Memory;
+export declare function loadMemory(file: string): Memory | null;
+/** Writes with sorted keys so the file diffs cleanly in review. */
+export declare function saveMemory(file: string, memory: Memory): void;
+export interface StaleVerdict {
+    stale: boolean;
+    tracked: boolean;
+}
+/**
+ * A translation is stale when the source moved and the translation demonstrably
+ * did not. If the target no longer matches what was recorded, someone edited it
+ * by hand — we cannot claim it is outdated, so we stay quiet.
+ */
+export declare function judge(entry: MemoryEntry | undefined, sourceValue: string, targetValue: string): StaleVerdict;
+export interface SyncOptions {
+    origin: 'human' | 'machine';
+    reviewed: boolean;
+    locales?: string[];
+    /** Accept the current state wholesale, clearing stale flags. */
+    force: boolean;
+}
+export interface SyncResult {
+    created: number;
+    updated: number;
+    keptStale: number;
+    unchanged: number;
+    removed: number;
+}
+/**
+ * Records the current translations. Without --force this never clears a stale
+ * flag: an entry whose target is unchanged keeps its old source hash, because
+ * nothing about the translation has actually been redone.
+ */
+export declare function syncMemory(config: Config, memory: Memory, opts: SyncOptions): SyncResult;

package/dist/memory.js

@@ -0,0 +1,162 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { loadBundle } from './scan.js';
+export const MEMORY_FILE = '.i18n/memory.json';
+/** Everything still waiting for a person to look at it, in a stable order. */
+export function unreviewed(memory, locales, keys) {
+    const wantedLocale = locales && locales.length > 0 ? new Set(locales) : null;
+    const wantedKey = keys && keys.length > 0 ? new Set(keys) : null;
+    const out = [];
+    for (const locale of Object.keys(memory.entries).sort()) {
+        if (wantedLocale && !wantedLocale.has(locale))
+            continue;
+        const byKey = memory.entries[locale] ?? {};
+        for (const key of Object.keys(byKey).sort()) {
+            if (wantedKey && !wantedKey.has(key))
+                continue;
+            const entry = byKey[key];
+            if (!entry.reviewed)
+                out.push({ locale, key, entry });
+        }
+    }
+    return out;
+}
+/**
+ * Signs off on translations a person has actually looked at.
+ *
+ * Nothing else in the tool can set this: a machine translation is recorded
+ * unreviewed and stays that way until someone says otherwise, which is the
+ * whole point of recording it.
+ */
+export function markReviewed(entries, now) {
+    for (const { entry } of entries) {
+        entry.reviewed = true;
+        entry.reviewedAt = now;
+    }
+    return entries.length;
+}
+export class MemoryError extends Error {
+}
+/** 48 bits is plenty to notice an edited string, and keeps the file readable. */
+export function hashValue(value) {
+    return createHash('sha256').update(value, 'utf8').digest('hex').slice(0, 12);
+}
+export function memoryPath(root, explicit) {
+    return resolve(root, explicit ?? MEMORY_FILE);
+}
+export function emptyMemory(sourceLocale) {
+    return { version: 1, sourceLocale, entries: {} };
+}
+export function loadMemory(file) {
+    if (!existsSync(file))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch (err) {
+        throw new MemoryError(`Invalid memory file ${file}\n  ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const memory = parsed;
+    if (memory?.version !== 1 || typeof memory.entries !== 'object' || memory.entries === null) {
+        throw new MemoryError(`Unrecognised memory file format in ${file} (expected version 1)`);
+    }
+    return { version: 1, sourceLocale: memory.sourceLocale ?? '', entries: memory.entries };
+}
+/** Writes with sorted keys so the file diffs cleanly in review. */
+export function saveMemory(file, memory) {
+    const entries = {};
+    for (const locale of Object.keys(memory.entries).sort()) {
+        const byKey = memory.entries[locale] ?? {};
+        const sorted = {};
+        for (const key of Object.keys(byKey).sort())
+            sorted[key] = byKey[key];
+        entries[locale] = sorted;
+    }
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, `${JSON.stringify({ version: 1, sourceLocale: memory.sourceLocale, entries }, null, 2)}\n`);
+}
+/**
+ * A translation is stale when the source moved and the translation demonstrably
+ * did not. If the target no longer matches what was recorded, someone edited it
+ * by hand — we cannot claim it is outdated, so we stay quiet.
+ */
+export function judge(entry, sourceValue, targetValue) {
+    if (!entry)
+        return { stale: false, tracked: false };
+    const moved = entry.sourceHash !== hashValue(sourceValue);
+    return { stale: moved && entry.value === targetValue, tracked: true };
+}
+/**
+ * Records the current translations. Without --force this never clears a stale
+ * flag: an entry whose target is unchanged keeps its old source hash, because
+ * nothing about the translation has actually been redone.
+ */
+export function syncMemory(config, memory, opts) {
+    const source = loadBundle(config, config.sourceLocale);
+    const result = { created: 0, updated: 0, keptStale: 0, unchanged: 0, removed: 0 };
+    const now = new Date().toISOString();
+    const wanted = opts.locales && opts.locales.length > 0 ? new Set(opts.locales) : null;
+    memory.sourceLocale = config.sourceLocale;
+    for (const locale of config.locales) {
+        if (locale === config.sourceLocale)
+            continue;
+        if (wanted && !wanted.has(locale))
+            continue;
+        const target = loadBundle(config, locale);
+        const byKey = (memory.entries[locale] ??= {});
+        for (const [key, sourceLeaf] of source.leaves) {
+            const targetLeaf = target.leaves.get(key);
+            if (!targetLeaf || targetLeaf.value.trim() === '')
+                continue;
+            const entry = byKey[key];
+            const sourceHash = hashValue(sourceLeaf.value);
+            if (!entry) {
+                byKey[key] = {
+                    sourceHash,
+                    value: targetLeaf.value,
+                    origin: opts.origin,
+                    reviewed: opts.reviewed,
+                    updatedAt: now,
+                };
+                result.created++;
+                continue;
+            }
+            const translationChanged = entry.value !== targetLeaf.value;
+            if (translationChanged || opts.force) {
+                if (entry.sourceHash === sourceHash && !translationChanged) {
+                    result.unchanged++;
+                    continue;
+                }
+                byKey[key] = {
+                    sourceHash,
+                    value: targetLeaf.value,
+                    origin: translationChanged ? opts.origin : entry.origin,
+                    reviewed: translationChanged ? opts.reviewed : entry.reviewed,
+                    updatedAt: now,
+                    // A sign-off survives a source edit; only a rewritten translation
+                    // invalidates it.
+                    ...(translationChanged || entry.reviewedAt === undefined
+                        ? {}
+                        : { reviewedAt: entry.reviewedAt }),
+                };
+                result.updated++;
+                continue;
+            }
+            if (entry.sourceHash !== sourceHash)
+                result.keptStale++;
+            else
+                result.unchanged++;
+        }
+        // Drop bookkeeping for keys that no longer exist in the source.
+        for (const key of Object.keys(byKey)) {
+            if (!source.leaves.has(key)) {
+                delete byKey[key];
+                result.removed++;
+            }
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=memory.js.map

package/dist/memory.js.map

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

package/dist/placeholders.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Placeholder extraction across the interpolation syntaxes that actually collide
+ * in the wild. Patterns are applied in a fixed order and every match is masked
+ * out of the working copy, so `{{name}}` is never also counted as `{name}`.
+ */
+export declare const DEFAULT_SYNTAXES: string[];
+export declare const ALL_SYNTAXES: string[];
+/** Returns a multiset of placeholder labels: `{name}` twice is not the same as once. */
+export declare function extractPlaceholders(text: string, syntaxes: string[]): Map<string, number>;
+export interface PlaceholderDiff {
+    missing: string[];
+    extra: string[];
+}
+/** What the target lost from the source, and what it invented. */
+export declare function diffPlaceholders(source: Map<string, number>, target: Map<string, number>): PlaceholderDiff;

package/dist/placeholders.js

@@ -0,0 +1,103 @@
+/**
+ * Placeholder extraction across the interpolation syntaxes that actually collide
+ * in the wild. Patterns are applied in a fixed order and every match is masked
+ * out of the working copy, so `{{name}}` is never also counted as `{name}`.
+ */
+const PATTERNS = {
+    // {{ name }} — mustache / i18next default
+    mustache: {
+        re: /\{\{\s*[#/^&]?\s*([\w.$-]+)\s*\}\}/g,
+        label: (m) => `{{${m[1]}}}`,
+    },
+    // %{name} — ruby i18n
+    ruby: {
+        re: /%\{\s*([\w.$-]+)\s*\}/g,
+        label: (m) => `%{${m[1]}}`,
+    },
+    // {count, plural, ...} — ICU complex argument; matched by its head so that
+    // nested braces in the sub-messages do not hide the argument name.
+    icu_complex: {
+        re: /\{\s*([\w.$-]+)\s*,\s*(plural|select|selectordinal|number|date|time)\b/g,
+        label: (m) => `{${m[1]},${m[2]}}`,
+    },
+    // {name} — ICU simple argument
+    icu: {
+        re: /\{\s*([\w.$-]+)\s*\}/g,
+        label: (m) => `{${m[1]}}`,
+    },
+    // %s, %d, %1$s — printf
+    printf: {
+        re: /%(?:(\d+)\$)?([sdifux])/g,
+        label: (m) => (m[1] ? `%${m[1]}$${m[2]}` : `%${m[2]}`),
+    },
+    // <0>...</0> — react-i18next <Trans> indices
+    tag: {
+        re: /<\/?(\d+)>/g,
+        label: (m) => m[0],
+    },
+    // :name — Laravel. Off by default: it false-positives on prose like
+    // "Warning:Important". Enabled automatically for PHP locale files.
+    // Laravel treats :name, :Name and :NAME as one placeholder rendered with
+    // different capitalisation, so they normalise to one label here.
+    laravel: {
+        re: /(?<![\w:]):([a-zA-Z][\w]*)/g,
+        label: (m) => `:${m[1].toLowerCase()}`,
+    },
+};
+/** Longest / most specific syntaxes first, so masking works. */
+const ORDER = ['mustache', 'ruby', 'icu_complex', 'icu', 'printf', 'tag', 'laravel'];
+export const DEFAULT_SYNTAXES = ['mustache', 'ruby', 'icu_complex', 'icu', 'printf', 'tag'];
+export const ALL_SYNTAXES = ORDER;
+const MASK = '\u0000';
+function maskSpans(text, spans) {
+    const chars = [...text];
+    for (const [start, end] of spans) {
+        for (let i = start; i < end && i < chars.length; i++)
+            chars[i] = MASK;
+    }
+    return chars.join('');
+}
+/** Returns a multiset of placeholder labels: `{name}` twice is not the same as once. */
+export function extractPlaceholders(text, syntaxes) {
+    const counts = new Map();
+    let masked = text;
+    for (const id of ORDER) {
+        if (!syntaxes.includes(id))
+            continue;
+        const spec = PATTERNS[id];
+        if (!spec)
+            continue;
+        const re = new RegExp(spec.re.source, spec.re.flags);
+        const spans = [];
+        let m;
+        while ((m = re.exec(masked)) !== null) {
+            if (m[0].length === 0) {
+                re.lastIndex++;
+                continue;
+            }
+            const label = spec.label(m);
+            counts.set(label, (counts.get(label) ?? 0) + 1);
+            spans.push([m.index, m.index + m[0].length]);
+        }
+        if (spans.length > 0)
+            masked = maskSpans(masked, spans);
+    }
+    return counts;
+}
+/** What the target lost from the source, and what it invented. */
+export function diffPlaceholders(source, target) {
+    const missing = [];
+    const extra = [];
+    for (const [label, count] of source) {
+        const got = target.get(label) ?? 0;
+        if (got < count)
+            missing.push(count - got > 1 ? `${label} x${count - got}` : label);
+    }
+    for (const [label, count] of target) {
+        const had = source.get(label) ?? 0;
+        if (count > had)
+            extra.push(count - had > 1 ? `${label} x${count - had}` : label);
+    }
+    return { missing, extra };
+}
+//# sourceMappingURL=placeholders.js.map

package/dist/placeholders.js.map

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

package/dist/plurals.d.ts

@@ -0,0 +1,59 @@
+/**
+ * CLDR plural categories, taken from the ICU data already in the runtime rather
+ * than a hand-maintained table: the table would go stale, and this is the same
+ * data the application itself will use at runtime.
+ */
+export declare const CATEGORY_NAMES: readonly ["zero", "one", "two", "few", "many", "other"];
+export type Category = (typeof CATEGORY_NAMES)[number];
+export declare function isCategory(name: string): name is Category;
+/**
+ * Categories CLDR defines for a locale, or null when we cannot tell.
+ *
+ * Intl.PluralRules silently falls back to the system locale for tags it does
+ * not know — asking for "zz" on a Russian machine reports four categories — so
+ * a resolved language subtag that does not match the request means "unknown"
+ * rather than a wrong answer.
+ */
+export declare function categoriesFor(locale: string): Set<string> | null;
+export interface PluralBlock {
+    arg: string;
+    type: 'plural' | 'selectordinal';
+    /** Keyword selectors: one, few, other … */
+    categories: Set<string>;
+    /** Exact selectors: =0, =1 … which are not CLDR categories. */
+    exact: Set<string>;
+}
+export interface IcuScan {
+    blocks: PluralBlock[];
+    error: string | null;
+}
+/** Whether the string is trying to be an ICU plural at all. */
+export declare function looksLikeIcuPlural(text: string): boolean;
+export declare function scanIcu(text: string): IcuScan;
+export interface SuffixKey {
+    base: string;
+    category: Category;
+    separator: '_' | '.';
+}
+export interface PluralGroup {
+    categories: Set<Category>;
+    /** Kept so a finding can name the keys as the project actually writes them. */
+    separator: '_' | '.';
+}
+/** i18next writes item_one; Rails and Symfony nest it as item.one. */
+export declare function splitPluralSuffix(key: string): SuffixKey | null;
+/**
+ * Groups keys like item_one / item_other into base -> categories.
+ *
+ * A group must carry `other`, which every CLDR plural set has. Without that
+ * test, Rails' `restrict_dependent_destroy.has_one` / `has_many` — ActiveRecord
+ * association names — read as a plural group and were asked to grow the forms
+ * their language requires.
+ */
+export declare function pluralGroups(keys: Iterable<string>): Map<string, PluralGroup>;
+/**
+ * Laravel picks a segment by position or by explicit {0} / [1,*] ranges, which
+ * is its own mechanism and not CLDR. All we can honestly compare is the segment
+ * count, so that is all this reports.
+ */
+export declare function pipeSegments(text: string): number;