@babelize/engine 0.0.0-stage → 0.1.2

package/dist/utils/glossary-match.js

@@ -0,0 +1,25 @@
+"use strict";
+/** Shared by the translate phase and locale QA so both judge glossary use the same way. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.containsGlossaryTranslation = containsGlossaryTranslation;
+/**
+ * Whether the required glossary translation appears in the output, allowing
+ * for inflection: each of its words must match a word in the output on a
+ * shared stem (Polish "obszar roboczy" → "obszarem roboczym", German
+ * "Arbeitsbereich" → "Arbeitsbereichs"). Scripts without spaces fall back to a
+ * substring check.
+ */
+function containsGlossaryTranslation(translated, required) {
+    const out = translated.toLowerCase();
+    const want = required.toLowerCase();
+    if (out.includes(want))
+        return true;
+    const outWords = out.split(/[^\p{L}\p{N}]+/u).filter(Boolean);
+    const wantWords = want.split(/[^\p{L}\p{N}]+/u).filter(Boolean);
+    if (wantWords.length === 0)
+        return true;
+    return wantWords.every((w) => {
+        const stem = w.slice(0, Math.max(3, w.length - 3));
+        return outWords.some((o) => o.startsWith(stem));
+    });
+}

package/dist/utils/html-extractor.d.ts

@@ -0,0 +1,8 @@
+import type { ExtractedString, Warning } from '../runtime/types';
+import type { Node } from 'node-html-parser';
+export declare function extractStringsFromHtml(content: string, filePath: string, detectFormats?: boolean): Promise<{
+    strings: ExtractedString[];
+    warnings: Warning[];
+}>;
+export declare function isTextNode(node: Node): boolean;
+export declare function isElementNode(node: Node): boolean;

package/dist/utils/html-extractor.js

@@ -0,0 +1,317 @@
+"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.extractStringsFromHtml = extractStringsFromHtml;
+exports.isTextNode = isTextNode;
+exports.isElementNode = isElementNode;
+const string_utils_1 = require("./string-utils");
+const detect_format_1 = require("./detect-format");
+// Void elements that can't have text content
+const VOID_ELEMENTS = new Set([
+    'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
+    'link', 'meta', 'param', 'source', 'track', 'wbr',
+]);
+// Tags to skip entirely (already handled by SKIP_TAGS + void elements)
+// Everything else is considered potentially translatable
+const TRANSLATABLE_ATTRS = new Set([
+    'alt', 'title', 'placeholder', 'aria-label', 'aria-description',
+]);
+async function extractStringsFromHtml(content, filePath, detectFormats) {
+    const { parse } = await Promise.resolve().then(() => __importStar(require('node-html-parser')));
+    const ctx = {
+        filePath,
+        fileContent: content,
+        strings: [],
+        seenTexts: new Set(),
+    };
+    const warnings = [];
+    const root = parse(content, {
+        comment: false,
+        blockTextElements: { script: true, style: true, noscript: true, pre: true },
+    });
+    walkNode(root, ctx, 1, warnings, detectFormats);
+    extractHeadStrings(root, ctx, warnings);
+    return { strings: ctx.strings, warnings };
+}
+function isTextNode(node) {
+    return node.nodeType === 3;
+}
+function isElementNode(node) {
+    return node.nodeType === 1;
+}
+function asElement(node) {
+    return node.nodeType === 1 ? node : null;
+}
+/**
+ * Whether any element at or above `node` carries a `data-i18n` attribute.
+ * `node` is the parent of the text node being considered.
+ */
+function hasDataI18nAncestor(node) {
+    let current = node;
+    while (current) {
+        if (isElementNode(current)) {
+            const el = asElement(current);
+            if (el && el.getAttribute('data-i18n'))
+                return true;
+        }
+        current = current.parentNode;
+    }
+    return false;
+}
+function walkNode(node, ctx, depth, warnings, detectFormats) {
+    if (depth > 100)
+        return;
+    if (isTextNode(node)) {
+        const text = node.text.trim();
+        if (!text || text.length < 2)
+            return;
+        const parent = node.parentNode;
+        if (!parent || !isElementNode(parent))
+            return;
+        // Honor data-i18n on ANY ancestor, not just the direct parent — an
+        // ancestor `<div data-i18n="k"><p>Text</p></div>` must not re-extract.
+        if (hasDataI18nAncestor(parent))
+            return;
+        const parentRaw = parent.rawTagName;
+        if (!parentRaw)
+            return;
+        const parentTagName = parentRaw.toLowerCase();
+        if (string_utils_1.SKIP_TAGS.has(parentTagName) || VOID_ELEMENTS.has(parentTagName))
+            return;
+        const hasCurrency = (0, string_utils_1.matchesCurrencyPattern)(text);
+        const hasDate = (0, string_utils_1.matchesDatePattern)(text);
+        const isDateOrCurrencyValue = (hasCurrency || hasDate) && text.length >= 3;
+        const format = detectFormats ? (0, detect_format_1.detectFormat)(text) : null;
+        if (!(0, string_utils_1.isTranslatableText)(text) && !isDateOrCurrencyValue && !format)
+            return;
+        if ((0, string_utils_1.containsPII)(text))
+            return;
+        if (format) {
+            warnings.push({
+                type: 'ambiguous-format',
+                file: ctx.filePath,
+                line: findLineNumber(node, ctx.fileContent),
+                message: `Detected ${format.class} format: "${text}". Will be replaced with Intl.* API call.`,
+                severity: 'warning',
+                dismissible: true,
+            });
+        }
+        else {
+            if (hasCurrency) {
+                warnings.push({
+                    type: 'hardcoded-currency',
+                    file: ctx.filePath,
+                    line: findLineNumber(node, ctx.fileContent),
+                    message: 'Hardcoded currency/number format detected. Use Intl.NumberFormat.',
+                });
+            }
+            if (hasDate) {
+                warnings.push({
+                    type: 'hardcoded-date',
+                    file: ctx.filePath,
+                    line: findLineNumber(node, ctx.fileContent),
+                    message: 'Hardcoded date format detected. Use Intl.DateTimeFormat.',
+                });
+            }
+        }
+        const isDateOrCurrencyOnly = isDateOrCurrencyValue && !(0, string_utils_1.isTranslatableText)(text);
+        let context = 'jsx-text';
+        if (format) {
+            context = 'format-string';
+        }
+        else if (isDateOrCurrencyOnly) {
+            context = hasCurrency ? 'hardcoded-currency' : 'hardcoded-date';
+        }
+        const line = findLineNumber(node, ctx.fileContent);
+        const contentKey = `${ctx.filePath}:${(0, string_utils_1.hashString)(text)}`;
+        if (!ctx.seenTexts.has(contentKey)) {
+            const id = `${ctx.filePath}:${line}:${(0, string_utils_1.hashString)(text)}`;
+            ctx.seenTexts.add(contentKey);
+            ctx.strings.push({
+                text,
+                file: ctx.filePath,
+                line,
+                column: 0,
+                context,
+                id,
+                detectedFormat: format ?? undefined,
+            });
+        }
+        return;
+    }
+    const element = asElement(node);
+    if (element) {
+        const raw = element.rawTagName;
+        if (!raw) {
+            for (const child of element.childNodes) {
+                if (isTextNode(child) || asElement(child)) {
+                    walkNode(child, ctx, depth + 1, warnings, detectFormats);
+                }
+            }
+            return;
+        }
+        const tagName = raw.toLowerCase();
+        for (const attr of TRANSLATABLE_ATTRS) {
+            const value = element.getAttribute(attr);
+            if (value && (0, string_utils_1.isTranslatableText)(value) && !(0, string_utils_1.containsPII)(value)) {
+                const line = findLineNumber(element, ctx.fileContent);
+                const contentKey = `${ctx.filePath}:${(0, string_utils_1.hashString)(value)}`;
+                if (!ctx.seenTexts.has(contentKey)) {
+                    const id = `${ctx.filePath}:${line}:${(0, string_utils_1.hashString)(value)}`;
+                    ctx.seenTexts.add(contentKey);
+                    ctx.strings.push({
+                        text: value,
+                        file: ctx.filePath,
+                        line,
+                        column: 0,
+                        context: 'jsx-attr',
+                        id,
+                    });
+                }
+            }
+        }
+        // Extract value attribute from <input type="button|submit|reset"> and <option>
+        if (tagName === 'input') {
+            const type = element.getAttribute('type')?.toLowerCase();
+            if (type === 'button' || type === 'submit' || type === 'reset') {
+                const value = element.getAttribute('value');
+                if (value && value.trim().length >= 2 && !(0, string_utils_1.containsPII)(value) && (0, string_utils_1.isTranslatableText)(value)) {
+                    const line = findLineNumber(element, ctx.fileContent);
+                    const contentKey = `${ctx.filePath}:${(0, string_utils_1.hashString)(value)}`;
+                    if (!ctx.seenTexts.has(contentKey)) {
+                        const id = `${ctx.filePath}:${line}:${(0, string_utils_1.hashString)(value)}`;
+                        ctx.seenTexts.add(contentKey);
+                        ctx.strings.push({
+                            text: value,
+                            file: ctx.filePath,
+                            line,
+                            column: 0,
+                            context: 'jsx-attr',
+                            id,
+                        });
+                    }
+                }
+            }
+        }
+        if (tagName === 'option') {
+            const value = element.getAttribute('value');
+            if (value && value.trim().length >= 2 && !(0, string_utils_1.containsPII)(value) && (0, string_utils_1.isTranslatableText)(value)) {
+                // Only extract if value differs from text content (avoid duplicates)
+                const textContent = element.textContent?.trim();
+                if (textContent && value !== textContent) {
+                    const line = findLineNumber(element, ctx.fileContent);
+                    const contentKey = `${ctx.filePath}:${(0, string_utils_1.hashString)(value)}`;
+                    if (!ctx.seenTexts.has(contentKey)) {
+                        const id = `${ctx.filePath}:${line}:${(0, string_utils_1.hashString)(value)}`;
+                        ctx.seenTexts.add(contentKey);
+                        ctx.strings.push({
+                            text: value,
+                            file: ctx.filePath,
+                            line,
+                            column: 0,
+                            context: 'jsx-attr',
+                            id,
+                        });
+                    }
+                }
+            }
+        }
+        if (string_utils_1.SKIP_TAGS.has(tagName) || VOID_ELEMENTS.has(tagName))
+            return;
+        for (const child of element.childNodes) {
+            if (isTextNode(child) || asElement(child)) {
+                walkNode(child, ctx, depth + 1, warnings, detectFormats);
+            }
+        }
+    }
+}
+function findLineNumber(node, fileContent) {
+    if (node.range) {
+        return (fileContent.slice(0, node.range[0]).match(/\n/g) || []).length + 1;
+    }
+    const raw = node.rawText || node.text || '';
+    if (!raw)
+        return 0;
+    const idx = fileContent.indexOf(raw);
+    if (idx === -1)
+        return 0;
+    return (fileContent.slice(0, idx).match(/\n/g) || []).length + 1;
+}
+function extractHeadStrings(root, ctx, _warnings) {
+    // <title>
+    const title = root.querySelector('title');
+    if (title) {
+        const text = title.textContent?.trim();
+        if (text && text.length >= 2 && !ctx.seenTexts.has(text)) {
+            const contentKey = `${ctx.filePath}:${(0, string_utils_1.hashString)(text)}`;
+            if (!ctx.seenTexts.has(contentKey)) {
+                const id = `${ctx.filePath}:title:${(0, string_utils_1.hashString)(text)}`;
+                ctx.seenTexts.add(contentKey);
+                ctx.strings.push({
+                    text,
+                    file: ctx.filePath,
+                    line: 0,
+                    column: 0,
+                    context: 'jsx-attr',
+                    id,
+                });
+            }
+        }
+    }
+    // Meta tags with content attribute
+    const metaTags = root.querySelectorAll('meta[name],meta[property]');
+    const seoAttrs = ['description', 'og:title', 'og:description', 'og:site_name', 'twitter:title', 'twitter:description'];
+    for (const meta of metaTags) {
+        const name = meta.getAttribute('name') || meta.getAttribute('property');
+        if (name && seoAttrs.includes(name)) {
+            const content = meta.getAttribute('content');
+            if (content && content.trim().length >= 2 && !ctx.seenTexts.has(content)) {
+                const contentKey = `${ctx.filePath}:${(0, string_utils_1.hashString)(content)}`;
+                if (!ctx.seenTexts.has(contentKey)) {
+                    const id = `${ctx.filePath}:meta:${(0, string_utils_1.hashString)(content)}`;
+                    ctx.seenTexts.add(contentKey);
+                    ctx.strings.push({
+                        text: content,
+                        file: ctx.filePath,
+                        line: 0,
+                        column: 0,
+                        context: 'jsx-attr',
+                        id,
+                    });
+                }
+            }
+        }
+    }
+}

package/dist/utils/i18next-icu.d.ts

@@ -0,0 +1,38 @@
+import type { WorkspaceInfo } from '../runtime/types';
+/** Libraries that call i18next's init themselves (the config is inside the library). */
+export declare const I18NEXT_WRAPPERS: string[];
+/** First line of i18n configs Babelize writes; Babelize may update a file that has it. */
+export declare const GENERATED_I18N_CONFIG_MARKER = "// @babelize-generated i18n config";
+/**
+ * Whether an i18next config was written by Babelize: the marker, or the
+ * signature of the template from before the marker existed.
+ */
+export declare function isGeneratedI18nConfig(content: string): boolean;
+export interface I18nextIcuStatus {
+    /** ICU messages ("Hello {name}", plurals) will be formatted at runtime. */
+    available: boolean;
+    /** The project initializes i18next itself (its own config, or a wrapper like next-i18next): Babelize must not add a second config. */
+    userOwnsInit: boolean;
+    /** A config the user owns that doesn't load i18next-icu (relative path). */
+    userConfig?: string;
+    /** Wrapper library that owns i18next's init, when that's how the project is set up. */
+    wrapper?: string;
+    /** Babelize-generated configs that don't load i18next-icu yet (relative paths); finalization adds it. */
+    generatedWithoutIcu: string[];
+}
+/**
+ * Can a react-i18next project format ICU messages at runtime? Decided by the
+ * config that actually initializes i18next — the files calling
+ * `.use(initReactI18next)` / `i18n.init(…)`:
+ *  - a config the user owns: only if it loads i18next-icu;
+ *  - Babelize's own config: yes (finalization adds i18next-icu to older ones);
+ *  - a wrapper that owns init (next-i18next, …): only if its config loads i18next-icu;
+ *  - nothing yet: yes, Babelize will generate the config.
+ * Without ICU, placeholders would show as raw `{user}`, so sentences stay
+ * fragments until the user adds i18next-icu.
+ */
+export declare function detectI18nextIcu(workspace: WorkspaceInfo): Promise<I18nextIcuStatus>;
+/** Add i18next-icu to a Babelize-generated config (idempotent). */
+export declare function addIcuToGeneratedConfig(content: string): string;
+/** The note shown when sentences stay fragments because the runtime can't format ICU. */
+export declare function missingIcuNote(status: I18nextIcuStatus): string | null;

package/dist/utils/i18next-icu.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;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GENERATED_I18N_CONFIG_MARKER = exports.I18NEXT_WRAPPERS = void 0;
+exports.isGeneratedI18nConfig = isGeneratedI18nConfig;
+exports.detectI18nextIcu = detectI18nextIcu;
+exports.addIcuToGeneratedConfig = addIcuToGeneratedConfig;
+exports.missingIcuNote = missingIcuNote;
+const path = __importStar(require("path"));
+const types_1 = require("../runtime/types");
+const file_utils_1 = require("./file-utils");
+/** Configs often live in src/lib, which extraction skips; only skip build output and dependencies here. */
+const CONFIG_SCAN_EXCLUDES = ['node_modules', '.git', '.next', 'dist', 'build', 'out', 'coverage', '*.test.*', '*.spec.*', '*.d.ts', '*.min.js'];
+/** Libraries that call i18next's init themselves (the config is inside the library). */
+exports.I18NEXT_WRAPPERS = ['next-i18next', 'remix-i18next', 'gatsby-plugin-react-i18next'];
+/** Config files those wrappers read, relative to the project root. */
+const WRAPPER_CONFIG_FILES = [
+    'next-i18next.config.js', 'next-i18next.config.mjs', 'next-i18next.config.cjs', 'next-i18next.config.ts',
+    'gatsby-config.js', 'gatsby-config.ts', 'remix.config.js',
+];
+/** First line of i18n configs Babelize writes; Babelize may update a file that has it. */
+exports.GENERATED_I18N_CONFIG_MARKER = '// @babelize-generated i18n config';
+/**
+ * Whether an i18next config was written by Babelize: the marker, or the
+ * signature of the template from before the marker existed.
+ */
+function isGeneratedI18nConfig(content) {
+    if (content.includes(exports.GENERATED_I18N_CONFIG_MARKER))
+        return true;
+    return (content.includes('export const t = i18n.t.bind(i18n);') &&
+        content.includes("loadPath: '/locales/{{lng}}.json'") &&
+        content.includes("bindI18nStore: 'added removed'"));
+}
+const loadsIcu = (content) => /['"]i18next-icu['"]/.test(content);
+/** The file initializes i18next for React: `.use(initReactI18next)` or `i18next.init(…)`. */
+function isI18nextInit(content) {
+    if (/\.use\(\s*initReactI18next\s*\)/.test(content))
+        return true;
+    return /from\s+['"]i18next['"]|require\(\s*['"]i18next['"]\s*\)/.test(content) && /\b(?:i18n|i18next|instance)\s*(?:\.use\([^)]*\)\s*)*\.init\s*\(/.test(content);
+}
+async function readSafe(file) {
+    try {
+        return (await (0, file_utils_1.readFile)(file)) ?? '';
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Can a react-i18next project format ICU messages at runtime? Decided by the
+ * config that actually initializes i18next — the files calling
+ * `.use(initReactI18next)` / `i18n.init(…)`:
+ *  - a config the user owns: only if it loads i18next-icu;
+ *  - Babelize's own config: yes (finalization adds i18next-icu to older ones);
+ *  - a wrapper that owns init (next-i18next, …): only if its config loads i18next-icu;
+ *  - nothing yet: yes, Babelize will generate the config.
+ * Without ICU, placeholders would show as raw `{user}`, so sentences stay
+ * fragments until the user adds i18next-icu.
+ */
+async function detectI18nextIcu(workspace) {
+    const seen = new Set();
+    const userConfigs = [];
+    const generatedWithoutIcu = [];
+    for (const dir of new Set(['.', ...workspace.sourceDirs])) {
+        let files = [];
+        try {
+            files = (await (0, file_utils_1.findFiles)(path.join(workspace.path, dir), types_1.SUPPORTED_EXTENSIONS, CONFIG_SCAN_EXCLUDES)) ?? [];
+        }
+        catch {
+            files = [];
+        }
+        for (const file of files) {
+            if (seen.has(file) || /[\\/]node_modules[\\/]/.test(file))
+                continue;
+            seen.add(file);
+            const content = await readSafe(file);
+            if (!isI18nextInit(content))
+                continue;
+            const rel = path.relative(workspace.path, file).split(path.sep).join('/');
+            if (isGeneratedI18nConfig(content)) {
+                if (!loadsIcu(content))
+                    generatedWithoutIcu.push(rel);
+            }
+            else {
+                userConfigs.push({ rel, icu: loadsIcu(content) });
+            }
+        }
+    }
+    if (userConfigs.length > 0) {
+        const without = userConfigs.find((c) => !c.icu);
+        return { available: !without, userOwnsInit: true, userConfig: without?.rel, generatedWithoutIcu };
+    }
+    const deps = { ...workspace.packageJson?.dependencies, ...workspace.packageJson?.devDependencies };
+    const wrapper = exports.I18NEXT_WRAPPERS.find((w) => deps[w]);
+    if (wrapper) {
+        let icu = false;
+        for (const name of WRAPPER_CONFIG_FILES) {
+            const file = path.join(workspace.path, name);
+            if ((await (0, file_utils_1.pathExists)(file).catch(() => false)) && loadsIcu(await readSafe(file)))
+                icu = true;
+        }
+        return { available: icu, userOwnsInit: true, wrapper, generatedWithoutIcu };
+    }
+    return { available: true, userOwnsInit: false, generatedWithoutIcu };
+}
+/** Add i18next-icu to a Babelize-generated config (idempotent). */
+function addIcuToGeneratedConfig(content) {
+    if (loadsIcu(content))
+        return content;
+    const importLine = "import ICU from 'i18next-icu';";
+    let out = content;
+    const detector = /^import LanguageDetector from ['"]i18next-browser-languagedetector['"];?\r?\n/m;
+    if (detector.test(out))
+        out = out.replace(detector, (m) => `${m}${importLine}\n`);
+    else
+        out = out.replace(/^(import i18n from ['"]i18next['"];?\r?\n)/m, `$1${importLine}\n`);
+    return out.replace(/\.use\(initReactI18next\)/, '.use(ICU)\n  .use(initReactI18next)');
+}
+/** The note shown when sentences stay fragments because the runtime can't format ICU. */
+function missingIcuNote(status) {
+    if (status.available)
+        return null;
+    if (status.wrapper) {
+        return `${status.wrapper} initializes i18next without i18next-icu, so JSX sentences with variables were kept as separate fragments. Add i18next-icu to enable full-sentence translation (add it to the \`use\` option of your ${status.wrapper} config).`;
+    }
+    return `${status.userConfig} doesn't load i18next-icu, so JSX sentences with variables were kept as separate fragments. Add i18next-icu to enable full-sentence translation: \`import ICU from 'i18next-icu'\` and \`.use(ICU)\`.`;
+}

package/dist/utils/icu-message.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Minimal ICU MessageFormat parser and validator for translated messages.
+ *
+ * ICU messages can't be tokenized like simple placeholders: a translation
+ * legitimately changes their structure (Polish needs `few`/`many` plural
+ * branches English doesn't have). So instead of protecting them, we let the
+ * model rewrite the whole message and then check the result is still a valid
+ * message with the same arguments and selector branches.
+ *
+ * Covers what UI strings use: simple and formatted arguments, plural,
+ * selectordinal (with offset and =n keys), select, `#`, and apostrophe
+ * quoting. Not a full ICU implementation (no nested formatting skeletons).
+ */
+export type IcuNode = {
+    type: 'text';
+    value: string;
+} | {
+    type: 'pound';
+} | {
+    type: 'argument';
+    name: string;
+    format?: string;
+} | {
+    type: 'plural' | 'selectordinal' | 'select';
+    name: string;
+    options: Record<string, IcuNode[]>;
+};
+export declare class IcuParseError extends Error {
+}
+export declare function parseIcu(message: string): IcuNode[];
+/** True when the message uses plural/select/selectordinal syntax. */
+export declare function isIcuMessage(message: string): boolean;
+export interface IcuIssue {
+    severity: 'error' | 'warning';
+    code: 'icu_invalid' | 'icu_arguments_changed' | 'icu_selector_removed' | 'icu_selector_added' | 'icu_branch_lost_argument' | 'icu_select_keys_changed' | 'icu_plural_category_invalid' | 'icu_missing_other' | 'icu_plural_category_missing';
+    message: string;
+}
+/**
+ * Compare a translated ICU message to its source. Errors mean the message is
+ * broken at runtime (unparseable, arguments renamed, select branches changed,
+ * no `other`). Missing target plural categories are only a warning: ICU
+ * falls back to `other` for them.
+ */
+export declare function compareIcuMessages(source: string, translated: string, targetLocale: string, options?: {
+    /**
+     * Simple arguments of the source the translation may turn into a plural
+     * (the count-like ones the engine flagged). A plural over any other
+     * argument is an error: `{name, plural, …}` formats a name as NaN.
+     */
+    pluralizable?: string[];
+}): IcuIssue[];
+export declare function isCountLikeName(name: string): boolean;
+/**
+ * Simple `{name}` arguments of a non-ICU message that look like counts. A
+ * translation may turn such an argument into a plural for languages that
+ * inflect words by number, without the source having to.
+ */
+export declare function countArguments(message: string): string[];
+/** Single-brace `{name}` arguments (not `{{name}}`). */
+export declare function extractSimpleArguments(message: string): string[];
+/** CLDR plural categories a translator should produce for this locale. */
+export declare function requiredPluralCategories(locale: string): {
+    cardinal: string[];
+    ordinal: string[];
+};