@katerynakhar/i18n-keeper 0.16.0

package/dist/apply.d.ts

@@ -0,0 +1,66 @@
+import type { Glossary } from './glossary.js';
+import { type Limits } from './lengths.js';
+import { type Memory } from './memory.js';
+import type { Config, LocaleBundle } from './types.js';
+import { type Proposal } from './translate.js';
+/**
+ * Applying accepted translations to locale files.
+ *
+ * Each format has its own writer, and none of them re-serialises a parsed tree:
+ * comments, quote styles, anchors and translator notes have to survive, so the
+ * writers edit text in place. What this module decides is which file a key
+ * belongs to, and whether a file that does not exist yet can be created — which
+ * only JSON and PHP can, since a YAML file's shape and a gettext header cannot
+ * be invented.
+ */
+export declare class ApplyError extends Error {
+}
+export interface Destination {
+    file: string;
+    /** The key as that file spells it, with any file-level namespace removed. */
+    key: string;
+    /** The source-locale file this one mirrors, used when creating it. */
+    sourceFile: string;
+}
+/** Where a translation for `key` belongs, or null when the format is unknown. */
+export declare function destinationFor(config: Config, source: LocaleBundle, locale: string, key: string): Destination | null;
+export interface ApplyResult {
+    written: number;
+    files: string[];
+    /** Translations that could not be written, and why. */
+    skipped: Array<{
+        locale: string;
+        key: string;
+        reason: string;
+    }>;
+}
+export declare function applyProposals(config: Config, source: LocaleBundle, proposals: Proposal[]): ApplyResult;
+export declare const SAVE_VERSION = 1;
+export interface SavedRun {
+    version: number;
+    model: string;
+    sourceLocale: string;
+    createdAt: string;
+    aborted: string | null;
+    proposals: Proposal[];
+}
+export declare function saveRun(file: string, run: SavedRun): void;
+export declare function loadRun(file: string): SavedRun;
+export interface Recheck {
+    ready: Proposal[];
+    dropped: Array<{
+        proposal: Proposal;
+        reason: string;
+    }>;
+}
+/**
+ * The gate runs again at apply time.
+ *
+ * A saved file can be days old and is editable by hand, so nothing is written
+ * on the strength of a check made earlier against files that may since have
+ * moved. A proposal whose source string has changed is dropped rather than
+ * applied to text it was not written for.
+ */
+export declare function recheck(config: Config, source: LocaleBundle, glossary: Glossary | null, limits: Limits | null, proposals: Proposal[]): Recheck;
+/** Machine output is recorded unreviewed, whichever command wrote it. */
+export declare function recordMachine(memory: Memory, proposals: Proposal[], now: string): void;

package/dist/apply.js

@@ -0,0 +1,254 @@
+import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, sep } from 'node:path';
+import { limitFor } from './lengths.js';
+import { hashValue } from './memory.js';
+import { writeJsonLocale } from './formats/json-write.js';
+import { blankPhpFile, writePhpLocale } from './formats/php-write.js';
+import { writePoLocale } from './formats/po-write.js';
+import { writeYamlLocale } from './formats/yaml-write.js';
+import { validate } from './translate.js';
+/**
+ * Applying accepted translations to locale files.
+ *
+ * Each format has its own writer, and none of them re-serialises a parsed tree:
+ * comments, quote styles, anchors and translator notes have to survive, so the
+ * writers edit text in place. What this module decides is which file a key
+ * belongs to, and whether a file that does not exist yet can be created — which
+ * only JSON and PHP can, since a YAML file's shape and a gettext header cannot
+ * be invented.
+ */
+export class ApplyError extends Error {
+}
+const WRITERS = new Map([
+    ['.json', writeJsonLocale],
+    ['.php', writePhpLocale],
+    ['.yaml', writeYamlLocale],
+    ['.yml', writeYamlLocale],
+    ['.pot', writePoLocale],
+    ['.po', writePoLocale],
+]);
+/**
+ * An empty file for a locale that has none yet, or null when its shape cannot
+ * be known. A YAML file depends on whether the project nests under a locale
+ * root, and a gettext catalogue needs a header declaring the language's own
+ * plural rules — neither can be invented.
+ */
+function blankFileFor(extension, sourceFile) {
+    if (extension === '.json')
+        return '{}\n';
+    if (extension === '.php') {
+        const source = existsSync(sourceFile) ? readFileSync(sourceFile, 'utf8') : null;
+        return blankPhpFile(source);
+    }
+    return null;
+}
+function extensionOf(file) {
+    const at = file.lastIndexOf('.');
+    return at === -1 ? '' : file.slice(at).toLowerCase();
+}
+function namespaceOf(config, sourceFile) {
+    const localeRoot = join(config.localesDir, config.sourceLocale);
+    return relative(localeRoot, sourceFile)
+        .replace(/\.[^.]+$/, '')
+        .split(sep)
+        .filter((part) => part !== 'LC_MESSAGES')
+        .join('.');
+}
+/**
+ * Which source file a key belongs to.
+ *
+ * Not every key the target needs exists in the source: a plural form only the
+ * target language has — Polish `items.few` against English `one`/`other` — has
+ * no source leaf at all. Such a key still belongs wherever its neighbours live,
+ * so the lookup walks up to the nearest prefix that does exist.
+ */
+function sourceFileFor(source, key) {
+    const leaf = source.leaves.get(key);
+    if (leaf)
+        return leaf.file;
+    const parts = key.split('.');
+    for (let depth = parts.length - 1; depth > 0; depth--) {
+        const prefix = `${parts.slice(0, depth).join('.')}.`;
+        for (const [candidate, candidateLeaf] of source.leaves) {
+            if (candidate.startsWith(prefix))
+                return candidateLeaf.file;
+        }
+    }
+    // i18next spells plurals as item_few rather than item.few.
+    const underscore = key.lastIndexOf('_');
+    if (underscore > 0) {
+        const base = `${key.slice(0, underscore)}_`;
+        for (const [candidate, candidateLeaf] of source.leaves) {
+            if (candidate.startsWith(base))
+                return candidateLeaf.file;
+        }
+    }
+    return source.files[0] ?? null;
+}
+/** Where a translation for `key` belongs, or null when the format is unknown. */
+export function destinationFor(config, source, locale, key) {
+    const from = sourceFileFor(source, key);
+    if (!from)
+        return null;
+    const extension = extensionOf(from);
+    if (!WRITERS.has(extension))
+        return null;
+    if (config.layout === 'flat') {
+        return { file: join(config.localesDir, `${locale}${extension}`), key, sourceFile: from };
+    }
+    const localeRoot = join(config.localesDir, config.sourceLocale);
+    const withinLocale = relative(localeRoot, from);
+    const namespace = namespaceOf(config, from);
+    const inner = namespace && key.startsWith(`${namespace}.`) ? key.slice(namespace.length + 1) : key;
+    return { file: join(config.localesDir, locale, withinLocale), key: inner, sourceFile: from };
+}
+export function applyProposals(config, source, proposals) {
+    const result = { written: 0, files: [], skipped: [] };
+    const byFile = new Map();
+    for (const proposal of proposals) {
+        if (!proposal.accepted)
+            continue;
+        const destination = destinationFor(config, source, proposal.locale, proposal.key);
+        if (!destination) {
+            result.skipped.push({
+                locale: proposal.locale,
+                key: proposal.key,
+                reason: 'no writer for this format',
+            });
+            continue;
+        }
+        const bucket = byFile.get(destination.file);
+        const edit = { key: destination.key, value: proposal.value };
+        if (bucket)
+            bucket.edits.push(edit);
+        else {
+            byFile.set(destination.file, {
+                locale: proposal.locale,
+                sourceFile: destination.sourceFile,
+                edits: [edit],
+            });
+        }
+    }
+    for (const [file, { locale, sourceFile, edits }] of byFile) {
+        const extension = extensionOf(file);
+        const writer = WRITERS.get(extension);
+        let content;
+        if (existsSync(file)) {
+            content = readFileSync(file, 'utf8');
+        }
+        else {
+            const blank = blankFileFor(extension, sourceFile);
+            if (blank === null) {
+                for (const edit of edits) {
+                    result.skipped.push({
+                        locale,
+                        key: edit.key,
+                        reason: `${file} does not exist and this format cannot be created from nothing`,
+                    });
+                }
+                continue;
+            }
+            content = blank;
+        }
+        let outcome;
+        try {
+            outcome = writer(content, file, locale, edits);
+        }
+        catch (err) {
+            throw new ApplyError(`Cannot write ${file}\n  ${err instanceof Error ? err.message : String(err)}`);
+        }
+        for (const skip of outcome.skipped) {
+            result.skipped.push({ locale, key: skip.key, reason: skip.reason });
+        }
+        mkdirSync(dirname(file), { recursive: true });
+        writeFileSync(file, outcome.content);
+        result.files.push(file);
+        result.written += edits.length - outcome.skipped.length;
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Saved runs
+// ---------------------------------------------------------------------------
+export const SAVE_VERSION = 1;
+export function saveRun(file, run) {
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, `${JSON.stringify(run, null, 2)}\n`);
+}
+export function loadRun(file) {
+    if (!existsSync(file))
+        throw new ApplyError(`Proposals file not found: ${file}`);
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch (err) {
+        throw new ApplyError(`Cannot read ${file}\n  ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const run = parsed;
+    if (!run || run.version !== SAVE_VERSION) {
+        throw new ApplyError(`Unrecognised proposals file ${file} (expected version ${SAVE_VERSION})`);
+    }
+    if (!Array.isArray(run.proposals))
+        throw new ApplyError(`${file} has no proposals array`);
+    return {
+        version: SAVE_VERSION,
+        model: run.model ?? 'unknown',
+        sourceLocale: run.sourceLocale ?? '',
+        createdAt: run.createdAt ?? '',
+        aborted: run.aborted ?? null,
+        proposals: run.proposals,
+    };
+}
+/**
+ * The gate runs again at apply time.
+ *
+ * A saved file can be days old and is editable by hand, so nothing is written
+ * on the strength of a check made earlier against files that may since have
+ * moved. A proposal whose source string has changed is dropped rather than
+ * applied to text it was not written for.
+ */
+export function recheck(config, source, glossary, limits, proposals) {
+    const ready = [];
+    const dropped = [];
+    for (const proposal of proposals) {
+        if (!proposal.accepted) {
+            dropped.push({ proposal, reason: 'was rejected when proposed' });
+            continue;
+        }
+        const leaf = source.leaves.get(proposal.key);
+        if (!leaf) {
+            dropped.push({ proposal, reason: 'the key is no longer in the source locale' });
+            continue;
+        }
+        if (leaf.value !== proposal.source) {
+            dropped.push({ proposal, reason: 'the source string changed after the proposal was made' });
+            continue;
+        }
+        const problems = validate(config, {
+            source: leaf.value,
+            locale: proposal.locale,
+            maxWidth: limits ? limitFor(limits, proposal.key) : null,
+        }, proposal.value, glossary);
+        if (problems.length > 0) {
+            dropped.push({ proposal, reason: problems.join('; ') });
+            continue;
+        }
+        ready.push(proposal);
+    }
+    return { ready, dropped };
+}
+/** Machine output is recorded unreviewed, whichever command wrote it. */
+export function recordMachine(memory, proposals, now) {
+    for (const proposal of proposals) {
+        const byKey = (memory.entries[proposal.locale] ??= {});
+        byKey[proposal.key] = {
+            sourceHash: hashValue(proposal.source),
+            value: proposal.value,
+            origin: 'machine',
+            reviewed: false,
+            updatedAt: now,
+        };
+    }
+}
+//# sourceMappingURL=apply.js.map

package/dist/apply.js.map

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

package/dist/check.d.ts

@@ -0,0 +1,5 @@
+import { type Glossary } from './glossary.js';
+import { type Limits } from './lengths.js';
+import { type Memory } from './memory.js';
+import type { Config, Report } from './types.js';
+export declare function check(config: Config, memory?: Memory | null, glossary?: Glossary | null, limits?: Limits | null): Report;

package/dist/check.js

@@ -0,0 +1,326 @@
+import { containsTerm, expectationsFor, missingVerbatim, } from './glossary.js';
+import { allowanceFor, limitFor, measurable, renderedWidth, } from './lengths.js';
+import { judge } from './memory.js';
+import { diffPlaceholders, extractPlaceholders } from './placeholders.js';
+import { categoriesFor, pipeSegments, pluralGroups, scanIcu, splitPluralSuffix, } from './plurals.js';
+import { loadBundle, sourceIsMsgid } from './scan.js';
+const HAS_LETTER = /\p{L}/u;
+/** gettext plural forms are indexed, not named: base.0, base.1, base.2. */
+const PLURAL_INDEX = /^(.*)\.(\d+)$/;
+function pluralIndexBase(key) {
+    const match = PLURAL_INDEX.exec(key);
+    return match ? match[1] : null;
+}
+function push(findings, config, rule, locale, key, file, detail) {
+    const setting = config.rules[rule];
+    if (setting === 'off')
+        return;
+    findings.push({ rule, severity: setting, locale, key, file, detail });
+}
+function list(categories) {
+    return [...categories].join('/');
+}
+/** ICU plural branches must cover the categories the target language actually has. */
+function checkIcuCategories(config, findings, locale, categories, key, file, value) {
+    const scan = scanIcu(value);
+    if (scan.error) {
+        push(findings, config, 'icu_syntax_error', locale, key, file, scan.error);
+        return;
+    }
+    if (!categories)
+        return;
+    for (const block of scan.blocks) {
+        const absent = [...categories].filter((c) => !block.categories.has(c));
+        if (absent.length > 0) {
+            push(findings, config, 'plural_missing_category', locale, key, file, `${locale} needs ${list(categories)}, has ${list(block.categories) || 'none'}`);
+        }
+        const extra = [...block.categories].filter((c) => !categories.has(c));
+        if (extra.length > 0) {
+            push(findings, config, 'plural_extra_category', locale, key, file, `${list(extra)} is not a plural category in ${locale}`);
+        }
+    }
+}
+/**
+ * The plural categories a target uses where the source had a plain string, or
+ * null when the expansion is something else.
+ */
+function pluralExpansion(target, key, categories) {
+    if (!categories)
+        return null;
+    const prefix = `${key}.`;
+    const used = new Set();
+    for (const candidate of target.leaves.keys()) {
+        if (!candidate.startsWith(prefix))
+            continue;
+        const rest = candidate.slice(prefix.length);
+        if (rest.includes('.') || !categories.has(rest))
+            return null;
+        used.add(rest);
+    }
+    return used.size > 0 ? used : null;
+}
+function checkLocale(config, source, target, findings, memory, glossary, limits) {
+    const before = findings.length;
+    for (const bad of target.unreadable) {
+        push(findings, config, 'unreadable_file', target.locale, bad.file, bad.file, bad.message);
+    }
+    const ignore = new Set(config.ignoreIdentical.map((s) => s.toLowerCase()));
+    const structuralPrefixes = [];
+    // Plural forms differ per language, so a key present in the source is not
+    // automatically required here, and a key absent from the source is not
+    // automatically dead.
+    const categories = categoriesFor(target.locale);
+    const sourceGroups = pluralGroups(source.leaves.keys());
+    const targetGroups = pluralGroups(target.leaves.keys());
+    const laravel = config.placeholderSyntaxes.includes('laravel');
+    let translated = 0;
+    let missing = 0;
+    let orphan = 0;
+    let stale = 0;
+    let notApplicable = 0;
+    // Only collected when the rule is on: one map per locale of source string ->
+    // the distinct translations it received.
+    const trackWording = config.rules.inconsistent_translation !== 'off';
+    const wordings = new Map();
+    for (const [key, sourceLeaf] of source.leaves) {
+        const targetLeaf = target.leaves.get(key);
+        if (!targetLeaf) {
+            const indexBase = pluralIndexBase(key);
+            if (indexBase && (source.plurals.has(indexBase) || target.plurals.has(indexBase))) {
+                // A catalogue carries as many forms as its own language needs.
+                notApplicable++;
+                continue;
+            }
+            const suffix = splitPluralSuffix(key);
+            if (suffix && sourceGroups.has(suffix.base) && categories && !categories.has(suffix.category)) {
+                // e.g. item_one has no counterpart in Japanese, which only has `other`.
+                notApplicable++;
+                continue;
+            }
+            const file = target.files[0] ?? target.locale;
+            if (target.containers.has(key)) {
+                structuralPrefixes.push(key + '.');
+                // Arabic turning one English string into zero/one/two/few/many is
+                // correct pluralisation, not a structural disagreement — so it is
+                // judged as a plural group instead.
+                const expanded = pluralExpansion(target, key, categories);
+                if (expanded) {
+                    const absent = [...categories].filter((c) => !expanded.has(c));
+                    if (absent.length > 0) {
+                        push(findings, config, 'plural_missing_category', target.locale, `${key}.*`, file, `${target.locale} needs ${list(categories)}, has ${list(expanded)}`);
+                    }
+                    continue;
+                }
+                push(findings, config, 'structure_mismatch', target.locale, key, file, 'value in source, object in target');
+            }
+            else {
+                missing++;
+                push(findings, config, 'missing_key', target.locale, key, file, 'not translated');
+            }
+            continue;
+        }
+        if (targetLeaf.value.trim() === '' && sourceLeaf.value.trim() !== '') {
+            // An empty string is not a translation. gettext spells that as an empty
+            // msgstr and i18next as "", and both mean the same as no key at all —
+            // so they are one finding, not two ideas wearing different names.
+            missing++;
+            push(findings, config, 'missing_key', target.locale, key, targetLeaf.file, 'present but empty');
+            // Nothing further can be true of an empty string: it has no placeholders
+            // to have lost, no plural forms to be missing, no width to overflow.
+            continue;
+        }
+        translated++;
+        if (targetLeaf.value === sourceLeaf.value &&
+            HAS_LETTER.test(sourceLeaf.value) &&
+            !ignore.has(sourceLeaf.value.toLowerCase())) {
+            push(findings, config, 'identical_to_source', target.locale, key, targetLeaf.file, `identical to source: "${truncate(sourceLeaf.value)}"`);
+        }
+        const sourcePlaceholders = extractPlaceholders(sourceLeaf.value, config.placeholderSyntaxes);
+        const targetPlaceholders = extractPlaceholders(targetLeaf.value, config.placeholderSyntaxes);
+        const { missing: lost, extra } = diffPlaceholders(sourcePlaceholders, targetPlaceholders);
+        if (lost.length > 0) {
+            push(findings, config, 'placeholder_missing', target.locale, key, targetLeaf.file, `${lost.join(', ')} lost`);
+        }
+        if (extra.length > 0) {
+            push(findings, config, 'placeholder_extra', target.locale, key, targetLeaf.file, `${extra.join(', ')} not in source`);
+        }
+        if (glossary) {
+            const lost = missingVerbatim(glossary, sourceLeaf.value, targetLeaf.value);
+            if (lost.length > 0) {
+                push(findings, config, 'dnt_violation', target.locale, key, targetLeaf.file, `${lost.join(', ')} must stay verbatim`);
+            }
+            for (const { term, accepted } of expectationsFor(glossary, target.locale, sourceLeaf.value)) {
+                const satisfied = accepted.some((form) => containsTerm(targetLeaf.value, form, term.match, term.caseSensitive));
+                if (!satisfied) {
+                    push(findings, config, 'glossary_violation', target.locale, key, targetLeaf.file, `"${term.source}" should be ${accepted.map((f) => `"${f}"`).join(' or ')}`);
+                }
+            }
+        }
+        if (trackWording && HAS_LETTER.test(sourceLeaf.value) && sourceLeaf.value.length >= 4) {
+            let variants = wordings.get(sourceLeaf.value);
+            if (!variants) {
+                variants = new Map();
+                wordings.set(sourceLeaf.value, variants);
+            }
+            if (!variants.has(targetLeaf.value))
+                variants.set(targetLeaf.value, key);
+        }
+        checkLength(config, findings, target.locale, key, targetLeaf.file, limits, laravel, targetLeaf.value, sourceLeaf.value);
+        checkIcuCategories(config, findings, target.locale, categories, key, targetLeaf.file, targetLeaf.value);
+        // Laravel selects a segment by position or explicit range, which is its own
+        // mechanism, not CLDR. The one thing that is unambiguously wrong is losing
+        // the selection entirely: trans_choice would then return one string for
+        // every count.
+        if (laravel && pipeSegments(sourceLeaf.value) > 1 && pipeSegments(targetLeaf.value) === 1) {
+            push(findings, config, 'plural_selector_lost', target.locale, key, targetLeaf.file, 'source selects between forms with |, translation has a single form');
+        }
+        const verdict = judge(memory?.entries[target.locale]?.[key], sourceLeaf.value, targetLeaf.value);
+        if (targetLeaf.fuzzy) {
+            // gettext already tracks this; no translation memory needed.
+            stale++;
+            push(findings, config, 'stale', target.locale, key, targetLeaf.file, 'marked fuzzy in the catalogue');
+        }
+        else if (verdict.stale) {
+            stale++;
+            push(findings, config, 'stale', target.locale, key, targetLeaf.file, 'source changed after this translation was recorded');
+        }
+        else if (memory && !verdict.tracked) {
+            push(findings, config, 'untracked', target.locale, key, targetLeaf.file, 'no memory entry; run sync');
+        }
+    }
+    for (const [key, leaf] of target.leaves) {
+        if (source.leaves.has(key))
+            continue;
+        // Already reported as a structure mismatch one level up; not a separate orphan.
+        if (structuralPrefixes.some((prefix) => key.startsWith(prefix)))
+            continue;
+        const indexBase = pluralIndexBase(key);
+        if (indexBase && (source.plurals.has(indexBase) || target.plurals.has(indexBase)))
+            continue;
+        const suffix = splitPluralSuffix(key);
+        if (suffix && sourceGroups.has(suffix.base) && categories?.has(suffix.category)) {
+            // e.g. item_few exists in Polish and not in English. That is the point.
+            continue;
+        }
+        if (source.containers.has(key)) {
+            push(findings, config, 'structure_mismatch', target.locale, key, leaf.file, 'object in source, value in target');
+            continue;
+        }
+        orphan++;
+        push(findings, config, 'orphan_key', target.locale, key, leaf.file, 'not in source locale');
+    }
+    // gettext states its own form count in the catalogue header, so this one is
+    // internally checkable without consulting CLDR at all.
+    if (target.nplurals !== null) {
+        for (const [base, forms] of target.plurals) {
+            if (forms === target.nplurals)
+                continue;
+            push(findings, config, 'plural_missing_category', target.locale, base, target.files[0] ?? target.locale, `header declares nplurals=${target.nplurals}, entry has ${forms}`);
+        }
+    }
+    // Suffix-key plural groups, checked per group rather than per key.
+    if (categories) {
+        for (const base of sourceGroups.keys()) {
+            const have = targetGroups.get(base);
+            if (!have)
+                continue; // the whole group is missing; already reported above
+            // Named the way the project writes it: item_one for i18next, item.one for
+            // Rails and Symfony.
+            const label = `${base}${have.separator}*`;
+            const absent = [...categories].filter((c) => !have.categories.has(c));
+            if (absent.length > 0) {
+                push(findings, config, 'plural_missing_category', target.locale, label, target.files[0] ?? target.locale, `${target.locale} needs ${list(categories)}, has ${list(have.categories)}`);
+            }
+            const extra = [...have.categories].filter((c) => !categories.has(c));
+            if (extra.length > 0) {
+                push(findings, config, 'plural_extra_category', target.locale, label, target.files[0] ?? target.locale, `${list(extra)} is not a plural category in ${target.locale}`);
+            }
+        }
+    }
+    for (const [sourceValue, variants] of wordings) {
+        if (variants.size < 2)
+            continue;
+        const keys = [...variants.values()];
+        push(findings, config, 'inconsistent_translation', target.locale, keys[0], target.files[0] ?? target.locale, `"${truncate(sourceValue)}" is translated ${variants.size} ways, also at ${keys.slice(1).join(', ')}`);
+    }
+    const added = findings.slice(before);
+    const applicable = source.leaves.size - notApplicable;
+    return {
+        locale: target.locale,
+        sourceKeys: source.leaves.size,
+        translated,
+        // Keys that the target language has no grammatical use for are left out of
+        // the denominator, so a complete Japanese locale still reads as 100%.
+        coverage: applicable <= 0 ? 1 : translated / applicable,
+        missing,
+        orphan,
+        stale,
+        errors: added.filter((f) => f.severity === 'error').length,
+        warnings: added.filter((f) => f.severity === 'warning').length,
+    };
+}
+/**
+ * Text is measured in display columns and only where measuring means something:
+ * an ICU plural holds every branch at once but shows one, and Laravel's pipes
+ * select between forms, so only the widest segment can ever appear.
+ */
+function checkLength(config, findings, locale, key, file, limits, laravel, value, sourceValue) {
+    if (!measurable(value))
+        return;
+    const width = renderedWidth(value, laravel);
+    const max = limits ? limitFor(limits, key) : null;
+    if (max !== null && width > max) {
+        push(findings, config, 'length_over_max', locale, key, file, `${width} columns, limit ${max}`);
+    }
+    if (sourceValue === null || !measurable(sourceValue))
+        return;
+    const sourceWidth = renderedWidth(sourceValue, laravel);
+    if (sourceWidth === 0)
+        return;
+    const allowed = allowanceFor(sourceWidth);
+    if (width > sourceWidth * allowed) {
+        const percent = Math.round((width / sourceWidth) * 100);
+        push(findings, config, 'length_overflow', locale, key, file, `${width} columns vs ${sourceWidth} in source — ${percent}%, allowance ${Math.round(allowed * 100)}%`);
+    }
+}
+/** A broken or oversized source string is broken for every language. */
+function checkSource(config, source, findings, limits) {
+    for (const bad of source.unreadable) {
+        push(findings, config, 'unreadable_file', source.locale, bad.file, bad.file, bad.message);
+    }
+    const categories = categoriesFor(source.locale);
+    const laravel = config.placeholderSyntaxes.includes('laravel');
+    for (const [key, leaf] of source.leaves) {
+        checkIcuCategories(config, findings, source.locale, categories, key, leaf.file, leaf.value);
+        checkLength(config, findings, source.locale, key, leaf.file, limits, laravel, leaf.value, null);
+    }
+}
+function truncate(value, max = 40) {
+    return value.length <= max ? value : `${value.slice(0, max - 1)}…`;
+}
+const SEVERITY_ORDER = { error: 0, warning: 1 };
+export function check(config, memory = null, glossary = null, limits = null) {
+    const source = loadBundle(config, config.sourceLocale);
+    const findings = [];
+    const stats = [];
+    checkSource(config, source, findings, limits);
+    for (const locale of config.locales) {
+        if (locale === config.sourceLocale)
+            continue;
+        stats.push(checkLocale(config, source, loadBundle(config, locale), findings, memory, glossary, limits));
+    }
+    findings.sort((a, b) => SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity] ||
+        a.locale.localeCompare(b.locale) ||
+        a.key.localeCompare(b.key) ||
+        a.rule.localeCompare(b.rule));
+    return {
+        localesDir: config.localesDir,
+        sourceLocale: config.sourceLocale,
+        sourceKeys: source.leaves.size,
+        sourceFromMsgid: sourceIsMsgid(source),
+        memoryLoaded: memory !== null,
+        stats,
+        findings,
+    };
+}
+//# sourceMappingURL=check.js.map