@ng-linguo/extract 0.9.0

package/src/lib/scan.js

@@ -0,0 +1,183 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractMessages = extractMessages;
+const normalize_1 = require("./normalize");
+// The `t` pipe: `'Play' | t` with an optional options object (`| t: { ... }`).
+// Group 2 is the key; group 3 is the options object (one level of nesting), from
+// which the context is read.
+const PIPE_PATTERN = /(['"])((?:\\.|(?!\1).)*?)\1\s*\|\s*t\b(?:\s*:\s*(\{(?:[^{}]|\{[^{}]*\})*\}))?/g;
+// `mark('...')` — the extraction marker for messages defined outside a template
+// (e.g. a component field). Not preceded by `.` so `foo.mark(...)` is ignored.
+// Group 2 is the key; group 3 is the optional options object (`mark('…', { … })`,
+// one level of nesting), from which the context is read.
+const MARK_PATTERN = /(?<!\.)\bmark\s*\(\s*(['"])((?:\\.|(?!\1).)*?)\1(?:\s*,\s*(\{(?:[^{}]|\{[^{}]*\})*\}))?/g;
+// The `t('...', { ... })` helper call (from `injectTranslate()`). The lookbehind
+// keeps it from matching `obj.t(`, `$t(`, or the tail of an identifier. Group 2
+// is the key; group 3 is the options object, from which the context is read.
+const T_CALL_PATTERN = /(?<![\w.$])t\s*\(\s*(['"])((?:\\.|(?!\1).)*?)\1(?:\s*,\s*(\{(?:[^{}]|\{[^{}]*\})*\}))?/g;
+// An element carrying the `[t]` directive via a static `t="message"` attribute.
+// `(?<![\w-])t\s*=` matches a standalone `t=` attribute (not `alt`, `data-t`,
+// `tParams`, `tContext`, `tFor`, nor bound `[t]="…"`). Group 2 is the message.
+const DIRECTIVE_TAG_PATTERN = /<[a-zA-Z][\w-]*\b[^>]*?(?<![\w-])t\s*=\s*"(?:\\.|[^"])*"[^>]*>/g;
+const DIRECTIVE_MESSAGE_PATTERN = /(?<![\w-])t\s*=\s*"((?:\\.|[^"])*)"/;
+const DIRECTIVE_CONTEXT_PATTERN = /(?<![\w-])tContext\s*=\s*"((?:\\.|[^"])*)"/;
+// Reads `context: '…'` out of a pipe options object.
+const CONTEXT_IN_OPTIONS = /\bcontext\s*:\s*(['"])((?:\\.|(?!\1).)*?)\1/;
+// Joins context and key for the dedup map (gettext EOT glue).
+const GLUE = String.fromCharCode(4);
+// Source-comment directives that exclude regions from extraction — for
+// documentation samples whose strings would otherwise scan as real messages.
+// Matched as plain substrings, so they work the same in `//`, `/* */`, and
+// `<!-- -->` comments without the scanner having to understand any of them.
+const IGNORE_FILE = 'linguo-ignore-file';
+const IGNORE_MARKER = /linguo-ignore-(next-line|start|end)/g;
+/**
+ * Character ranges of `content` excluded from extraction by `linguo-ignore`
+ * directives:
+ *
+ * - `linguo-ignore-file` anywhere — skip the whole file.
+ * - `linguo-ignore-start` … `linguo-ignore-end` — skip everything between them;
+ *   an unmatched `start` skips to end of file.
+ * - `linguo-ignore-next-line` — skip the single line after the directive.
+ */
+function ignoredRanges(content) {
+    if (content.includes(IGNORE_FILE)) {
+        return [{ start: 0, end: content.length }];
+    }
+    const ranges = [];
+    let blockStart = null;
+    IGNORE_MARKER.lastIndex = 0;
+    let match;
+    while ((match = IGNORE_MARKER.exec(content)) !== null) {
+        const kind = match[1];
+        if (kind === 'next-line') {
+            const lineEnd = content.indexOf('\n', match.index);
+            if (lineEnd === -1) {
+                continue; // directive on the last line — nothing follows to skip
+            }
+            const after = content.indexOf('\n', lineEnd + 1);
+            ranges.push({ start: lineEnd + 1, end: after === -1 ? content.length : after });
+        }
+        else if (kind === 'start') {
+            blockStart ??= match.index;
+        }
+        else if (kind === 'end' && blockStart !== null) {
+            ranges.push({ start: blockStart, end: match.index });
+            blockStart = null;
+        }
+    }
+    if (blockStart !== null) {
+        ranges.push({ start: blockStart, end: content.length });
+    }
+    return ranges;
+}
+function unescapeJs(value) {
+    return value.replace(/\\([\\'"`ntr])/g, (_match, char) => {
+        if (char === 'n')
+            return '\n';
+        if (char === 't')
+            return '\t';
+        if (char === 'r')
+            return '\r';
+        return char;
+    });
+}
+function lineOf(content, index) {
+    let line = 1;
+    for (let i = 0; i < index && i < content.length; i += 1) {
+        if (content[i] === '\n') {
+            line += 1;
+        }
+    }
+    return line;
+}
+function record(into, found, reference) {
+    if (found.keyId === '') {
+        return;
+    }
+    const id = found.context === '' ? found.keyId : `${found.context}${GLUE}${found.keyId}`;
+    const occurrence = into.get(id) ?? {
+        keyId: found.keyId,
+        context: found.context,
+        refs: new Set(),
+    };
+    occurrence.refs.add(reference);
+    into.set(id, occurrence);
+}
+/**
+ * Scan source files for translatable strings used by the `t` pipe
+ * (`'Play' | t: { context }`), the `[t]` directive (`t="message"` with an
+ * optional `tContext`), the `t('...', { context })` helper call, and the
+ * `mark()` marker, returning one {@link ExtractedMessage} per unique
+ * (context, key) pair with all of its source references.
+ *
+ * Pure and DOM-free, so it runs in CI on plain Node (CLAUDE.md §2.1). Entries
+ * are returned in order of discovery — files in the order given, and within a
+ * file by source position — so re-extraction produces a stable, readable order.
+ *
+ * Regions marked with `linguo-ignore` comment directives are skipped, so
+ * documentation samples containing `mark(`, `'…' | t`, or `t="…"` are not
+ * scanned as real messages (see {@link ignoredRanges}).
+ */
+function extractMessages(files) {
+    const occurrences = new Map();
+    for (const file of files) {
+        const found = [];
+        const fromOptions = (index, key, options) => {
+            const contextMatch = options ? CONTEXT_IN_OPTIONS.exec(options) : null;
+            found.push({
+                index,
+                keyId: (0, normalize_1.normalizeMessage)(unescapeJs(key)),
+                context: contextMatch ? unescapeJs(contextMatch[2] ?? '').trim() : '',
+            });
+        };
+        PIPE_PATTERN.lastIndex = 0;
+        let pipeMatch;
+        while ((pipeMatch = PIPE_PATTERN.exec(file.content)) !== null) {
+            fromOptions(pipeMatch.index, pipeMatch[2] ?? '', pipeMatch[3]);
+        }
+        MARK_PATTERN.lastIndex = 0;
+        let markMatch;
+        while ((markMatch = MARK_PATTERN.exec(file.content)) !== null) {
+            fromOptions(markMatch.index, markMatch[2] ?? '', markMatch[3]);
+        }
+        T_CALL_PATTERN.lastIndex = 0;
+        let callMatch;
+        while ((callMatch = T_CALL_PATTERN.exec(file.content)) !== null) {
+            fromOptions(callMatch.index, callMatch[2] ?? '', callMatch[3]);
+        }
+        DIRECTIVE_TAG_PATTERN.lastIndex = 0;
+        let tagMatch;
+        while ((tagMatch = DIRECTIVE_TAG_PATTERN.exec(file.content)) !== null) {
+            const tag = tagMatch[0];
+            const messageMatch = DIRECTIVE_MESSAGE_PATTERN.exec(tag);
+            if (!messageMatch) {
+                continue;
+            }
+            const contextMatch = DIRECTIVE_CONTEXT_PATTERN.exec(tag);
+            found.push({
+                index: tagMatch.index,
+                keyId: (0, normalize_1.normalizeMessage)(messageMatch[1] ?? ''),
+                context: contextMatch ? (contextMatch[1]?.trim() ?? '') : '',
+            });
+        }
+        // Interleave pipe and directive matches by source position so discovery
+        // order reflects how the file actually reads.
+        found.sort((a, b) => a.index - b.index);
+        const ignored = ignoredRanges(file.content);
+        const isIgnored = (index) => ignored.some((range) => index >= range.start && index < range.end);
+        for (const item of found) {
+            if (isIgnored(item.index)) {
+                continue;
+            }
+            record(occurrences, item, `${file.path}:${lineOf(file.content, item.index)}`);
+        }
+    }
+    // Map preserves insertion order, so this is discovery order.
+    return [...occurrences.values()].map(({ keyId, context, refs }) => ({
+        keyId,
+        context,
+        references: [...refs].sort(),
+    }));
+}
+//# sourceMappingURL=scan.js.map

package/src/lib/scan.js.map

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

package/src/lib/translation-prompt.txt

@@ -0,0 +1,214 @@
+You are a professional software localizer. Translate a gettext `.po`
+catalog produced by **ng-linguo** (an Angular i18n library) from English
+into {{TARGET_LANGUAGE}}.
+
+Return the COMPLETE `.po` file and NOTHING else — no commentary, no code
+fences, no explanations. Your output must be a valid `.po` file that I
+can save directly over the input.
+
+================================================================
+1. WHAT YOU MAY AND MAY NOT CHANGE
+================================================================
+A `.po` file is a list of entries. A typical entry looks like:
+
+    #: apps/playground/src/app/app.html:10
+    msgctxt "audio player"
+    msgid "Play"
+    msgstr "<MISSING TRANSLATION> Play"
+
+Rules:
+- TRANSLATE ONLY the text inside `msgstr "..."`.
+- NEVER change `msgid` — it is the source key. Copy it as-is.
+- NEVER change, remove, or reorder `#:` reference lines (source
+  locations) or `msgctxt` lines. Keep every entry in its original order.
+- Keep the header entry (the first block, `msgid ""` / `msgstr ""`)
+  exactly as-is.
+- Output every entry. Do not drop, merge, or add entries.
+
+================================================================
+2. WHICH ENTRIES NEED WORK — the <MISSING TRANSLATION> marker
+================================================================
+Any `msgstr` beginning with `<MISSING TRANSLATION>` is an untranslated
+entry seeded with the English source as a fallback.
+
+- For each such entry: translate the source and write the result WITHOUT
+  the `<MISSING TRANSLATION>` prefix (delete the prefix entirely).
+- If a `msgstr` does NOT start with that prefix, it is already
+  human-reviewed — LEAVE IT UNTOUCHED.
+
+================================================================
+3. CONTEXT — use it, never translate it
+================================================================
+`msgctxt "..."` carries the message's context. In ng-linguo, context is
+a single property that does two jobs:
+  (a) it disambiguates identical source text — the same `msgid "Play"`
+      can appear several times with different `msgctxt` ("audio player"
+      vs "game") and MUST be translated differently per context;
+  (b) it doubles as a translator note describing intent.
+
+So: READ the `msgctxt` to pick the right wording, but it is metadata —
+do not translate it and do not copy it into the `msgstr`. Entries with
+the same `msgid` but different `msgctxt` are independent and usually need
+different translations.
+
+================================================================
+4. SLOT TAGS — `[name]...[/name]`
+================================================================
+Some sources contain slot tags (a BBCode-like bracket syntax), e.g.:
+
+    msgid "Read the [docs]documentation[/docs] to get started"
+
+These tags map to interactive UI (links, buttons) at runtime.
+
+- Preserve every tag EXACTLY: same name, same `[name]` ... `[/name]`
+  pairing, same order. Tag names are NOT translated.
+- Translate ONLY the human text, including the text WRAPPED BY a tag.
+- You MAY move a tag pair to wherever the wrapped phrase naturally lands
+  in {{TARGET_LANGUAGE}} word order, as long as the pair stays matched
+  and wraps the same concept.
+- A literal `[` is written as a doubled `[[` — the ONLY escape in this
+  syntax. `[[` is NOT a slot tag; it renders as a single visible `[`.
+  Keep every `[[` exactly as a doubled bracket (never collapse it to one
+  `[`, never expand it) and translate the prose around it. So
+  `[[b]bold[[/b]` displays the literal characters `[b]bold[/b]`, and a
+  sentence built around that is describing the escape mechanism itself.
+
+Example (→ German):
+  msgid  "Read the [docs]documentation[/docs] to get started"
+  msgstr "Lies die [docs]Dokumentation[/docs], um loszulegen"
+
+================================================================
+5. ICU MESSAGEFORMAT 2 — the heart of translation quality
+================================================================
+ng-linguo formats messages with **MessageFormat 2 (MF2)**. Two forms
+appear:
+
+5a. SIMPLE PLACEHOLDERS — `{$name}`
+    msgid "Hello {$name}!"
+    A `{$var}` is a runtime value substituted into the sentence.
+    - Keep the placeholder verbatim, including the `$` and exact name.
+    - Reposition it to fit natural target word order.
+    - Do NOT invent, rename, or drop placeholders.
+    Example (→ Polish):
+      msgid  "Hello {$name}!"
+      msgstr "Cześć {$name}!"
+
+5b. SELECTION / PLURALS — `.input` / `.match` / variants
+    msgid ".input {$count :number} .match $count one {{{$count} file}} * {{{$count} files}}"
+
+    Anatomy:
+      .input {$count :number}   declares a selector value (a number)
+      .match $count             selects a variant based on it
+      one {{ ... }}             variant chosen for the "one" plural category
+      *   {{ ... }}             the catch-all / "other" variant (REQUIRED)
+      {{ ... }}                 a "quoted pattern": its inner text is what
+                                renders; `{$count}` inside it is a placeholder.
+
+    THIS IS WHERE QUALITY IS WON OR LOST. Different languages have
+    different CLDR plural categories. You MUST emit the categories that
+    {{TARGET_LANGUAGE}} actually uses — not copy English's set.
+
+    Rules:
+    - Keep `.input ... .match ...` and the selector exactly as written
+      (same `{$count :number}`, same `.match $count`).
+    - Replace the English variant KEYS with the correct CLDR plural
+      categories for {{TARGET_LANGUAGE}}, chosen from:
+        zero · one · two · few · many · other
+      Always include the `*` (other) catch-all variant.
+    - Translate ONLY the literal text inside each `{{ ... }}` pattern.
+      Keep `{$count}` (and any other `{$var}`) intact inside the pattern.
+    - Add or remove variants as the language requires (e.g. English has
+      one/other; Polish needs one/few/many/other).
+
+    Example (English `one` + `other`  →  Polish `one`/`few`/`many`/`other`):
+      msgid  ".input {$count :number} .match $count one {{{$count} file}} * {{{$count} files}}"
+      msgstr ".input {$count :number} .match $count one {{{$count} plik}} few {{{$count} pliki}} many {{{$count} plików}} * {{{$count} pliku}}"
+
+    Example (German, like English — one/other):
+      msgstr ".input {$count :number} .match $count one {{{$count} Datei}} * {{{$count} Dateien}}"
+
+    If you are unsure which plural categories a language uses, follow the
+    Unicode CLDR plural rules for that language. Getting these categories
+    right is the single most important part of this task.
+
+5c. GOING BEYOND THE SOURCE STRUCTURE
+    The English source is a baseline, not a cage. MF2 lets the target
+    read more naturally than a literal mirror of the source — use it.
+
+    (i) EXACT-VALUE MATCHING — special-case 0 (and sometimes 1).
+        `.match` keys may be literal numbers, and an exact literal wins
+        over a plural category. If {{TARGET_LANGUAGE}} phrases "none"
+        (or "one") with a different construction, ADD a literal variant.
+        This is always safe — it reuses the selector that already exists.
+
+        Example (→ English-style, but adding a natural zero case):
+          source variants:  one {{...}} * {{...}}
+          improved:         .match $count
+                            0   {{No files}}
+                            one {{One file}}
+                            *   {{{$count} files}}
+
+    (ii) ADDING A SELECTOR DIMENSION (gender, case, animacy …).
+        Many languages inflect on gender/case even where English does not.
+        You MAY add such a dimension ONLY IF a matching `.input {$var ...}`
+        is ALREADY DECLARED in the message (i.e. the app passes that value
+        at runtime). Never invent a selector for a variable that is not
+        already declared — at runtime it would be undefined and break.
+
+        When a selector IS available, switch to multiple selectors with
+        one key per selector on each variant line, and keep a `* * {{...}}`
+        catch-all:
+          .input {$count :number} .input {$gender :string}
+          .match $count $gender
+          one feminine  {{...}}
+          one masculine {{...}}
+          *   *         {{...}}
+
+        If the variable you would need is NOT declared, translate within
+        the source's existing structure instead — do not add it.
+
+================================================================
+6. MECHANICAL .po RULES
+================================================================
+- A `msgstr` value is a double-quoted string. Escape a literal double
+  quote as `\"` and a newline as `\n` inside the quotes.
+- Preserve any `""` continuation-line formatting if present (a value
+  split across multiple quoted lines concatenates).
+- UTF-8 throughout. Use the target language's real characters (ą, ß, é …),
+  not ASCII transliterations.
+
+================================================================
+7. STYLE
+================================================================
+- Translate meaning, not words. Match the register a UI button / label /
+  sentence would use in {{TARGET_LANGUAGE}}.
+- Aim for a result that reads as if ORIGINALLY WRITTEN in
+  {{TARGET_LANGUAGE}}, not transcoded from English. You are free to
+  restructure: reorder clauses, split one sentence into two or merge two
+  into one, change voice, drop filler connectives — whatever natural
+  phrasing wants. The source fixes the MEANING and the
+  placeholders/slots/tags, not the word order or sentence shape. Output
+  that is grammatical but stiff, word-for-word, or obviously translated is
+  a FAILURE here. Mirroring English clause order often produces broken
+  target grammar — rebuild the sentence instead.
+- Infer each message's DOMAIN and register from its own content and the
+  app's other strings — it may be software, medical, legal, finance,
+  gaming, marketing, hospitality, anything. Then translate the way a
+  domain expert writing in {{TARGET_LANGUAGE}} would, using that field's
+  established terminology — not a literal everyday rendering, and not
+  jargon borrowed from the wrong field. Technical terms usually have a
+  settled target-language form — sometimes a native word, sometimes a
+  borrowed or anglicized term that practitioners actually say; use
+  whichever is REAL in the field, not a coined literal calque. You do NOT need a
+  `msgctxt` to do this — the source text itself is the signal (treat
+  `msgctxt`, when present, as a tie-breaker). Example: in "Escaped
+  [[b]bold[[/b] stays literal" the surrounding markup marks a software
+  context, so "Escaped" is character-escaping — pick the term a developer
+  uses, not the word for fleeing/running away.
+- Respect the context (§3) when the same source has several entries.
+- Keep capitalization and punctuation idiomatic for the target language.
+
+================================================================
+NOW TRANSLATE THIS FILE
+================================================================
+{{PO_FILE}}

package/src/lib/translator.d.ts

@@ -0,0 +1,83 @@
+/**
+ * What a consumer's translate function receives. We build the prompt (explaining
+ * ng-linguo's context, slot tags and MessageFormat 2 rules) and parse the reply;
+ * the function's only job is to send `prompt` to an AI provider and return the
+ * model's raw answer — a complete `.po` block. This keeps every provider SDK and
+ * API secret on the consumer's side, out of this build-time tool.
+ */
+export interface TranslateRequest {
+    /** The ready-to-send prompt for the untranslated entries of one catalog. */
+    readonly prompt: string;
+    /** The catalog's locale code, e.g. `"pl"`. */
+    readonly targetLocale: string;
+    /** A human-readable label for the locale, e.g. `"Polish (pl)"`. */
+    readonly targetLabel: string;
+    /** The configured source locale the strings are translated from, e.g. `"en"`. */
+    readonly sourceLocale: string;
+}
+/**
+ * A consumer-supplied translation function. Linked to the build via the
+ * `translator` field in `linguo.config.json` (a path to a module that exports it
+ * as `translate` or as the default export). It receives a {@link TranslateRequest}
+ * and returns the model's reply — the translated `.po` text — sync or async.
+ *
+ * @example
+ * ```js
+ * // linguo.translator.mjs
+ * import OpenAI from 'openai';
+ * const client = new OpenAI(); // reads OPENAI_API_KEY
+ *
+ * export async function translate({ prompt }) {
+ *   const res = await client.chat.completions.create({
+ *     model: 'gpt-4o',
+ *     messages: [{ role: 'user', content: prompt }],
+ *   });
+ *   return res.choices[0].message.content ?? '';
+ * }
+ * ```
+ */
+export type TranslateFunction = (request: TranslateRequest) => string | Promise<string>;
+/**
+ * Extract the {@link TranslateFunction} from an imported translator module,
+ * accepting either a named `translate` export or a default function. Pure (no
+ * I/O), so it is unit-tested directly.
+ *
+ * @throws when no usable function is exported.
+ */
+export declare function resolveTranslatorExport(mod: unknown, source?: string): TranslateFunction;
+/** How a module specifier is loaded; injectable so the loader is testable. */
+export type ModuleImporter = (specifier: string) => Promise<unknown>;
+/**
+ * Dynamically import the translator module at `resolvedPath` (an absolute path)
+ * and return its {@link TranslateFunction}. The path is converted to a `file://`
+ * URL so ESM `.mjs`/`.js` consumer modules load on every platform.
+ *
+ * @throws when the module cannot be loaded or exports no usable function.
+ */
+export declare function loadTranslator(resolvedPath: string, importer?: ModuleImporter): Promise<TranslateFunction>;
+/** Outcome of {@link autoTranslateCatalog}. */
+export interface AutoTranslateOutcome {
+    /** How many entries were sent to the translator (the untranslated ones). */
+    readonly untranslated: number;
+    /** How many entries received a usable new translation. */
+    readonly applied: number;
+    /** How many entries are still untranslated after merging the reply. */
+    readonly remaining: number;
+    /** The merged full catalog as `.po` text (unchanged when nothing applied). */
+    readonly po: string;
+}
+/**
+ * Translate one catalog's untranslated entries by calling a {@link TranslateFunction}.
+ * Builds the prompt from the missing entries only, invokes `translate`, and folds
+ * the reply back into the full catalog. Pure of file I/O — the caller reads and
+ * writes the `.po` — so it is unit-tested with a fake translate function.
+ *
+ * @throws when the translator returns an empty reply.
+ */
+export declare function autoTranslateCatalog(args: {
+    readonly translate: TranslateFunction;
+    readonly poText: string;
+    readonly targetLocale: string;
+    readonly targetLabel: string;
+    readonly sourceLocale: string;
+}): Promise<AutoTranslateOutcome>;

package/src/lib/translator.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveTranslatorExport = resolveTranslatorExport;
+exports.loadTranslator = loadTranslator;
+exports.autoTranslateCatalog = autoTranslateCatalog;
+const node_url_1 = require("node:url");
+const apply_1 = require("./apply");
+const po_1 = require("./po");
+const prompt_1 = require("./prompt");
+function pickExport(mod) {
+    if (typeof mod !== 'object' || mod === null) {
+        return undefined;
+    }
+    const record = mod;
+    if (typeof record['translate'] === 'function') {
+        return record['translate'];
+    }
+    const def = record['default'];
+    if (typeof def === 'function') {
+        return def;
+    }
+    // An ESM module whose default export is itself an object with `translate`.
+    if (typeof def === 'object' && def !== null) {
+        const defRecord = def;
+        if (typeof defRecord['translate'] === 'function') {
+            return defRecord['translate'];
+        }
+    }
+    return undefined;
+}
+/**
+ * Extract the {@link TranslateFunction} from an imported translator module,
+ * accepting either a named `translate` export or a default function. Pure (no
+ * I/O), so it is unit-tested directly.
+ *
+ * @throws when no usable function is exported.
+ */
+function resolveTranslatorExport(mod, source = 'translator module') {
+    const candidate = pickExport(mod);
+    if (typeof candidate !== 'function') {
+        throw new Error(`${source} must export a "translate" function (named export) or a default function.`);
+    }
+    return candidate;
+}
+/**
+ * Dynamically import the translator module at `resolvedPath` (an absolute path)
+ * and return its {@link TranslateFunction}. The path is converted to a `file://`
+ * URL so ESM `.mjs`/`.js` consumer modules load on every platform.
+ *
+ * @throws when the module cannot be loaded or exports no usable function.
+ */
+async function loadTranslator(resolvedPath, importer = (specifier) => import(specifier)) {
+    const href = (0, node_url_1.pathToFileURL)(resolvedPath).href;
+    let mod;
+    try {
+        mod = await importer(href);
+    }
+    catch (error) {
+        throw new Error(`could not load translator module at ${resolvedPath}: ` +
+            `${error instanceof Error ? error.message : String(error)}`);
+    }
+    return resolveTranslatorExport(mod, resolvedPath);
+}
+/**
+ * Translate one catalog's untranslated entries by calling a {@link TranslateFunction}.
+ * Builds the prompt from the missing entries only, invokes `translate`, and folds
+ * the reply back into the full catalog. Pure of file I/O — the caller reads and
+ * writes the `.po` — so it is unit-tested with a fake translate function.
+ *
+ * @throws when the translator returns an empty reply.
+ */
+async function autoTranslateCatalog(args) {
+    const untranslated = (0, po_1.parsePo)(args.poText).filter((e) => (0, apply_1.isUntranslated)(e.msgstr));
+    if (untranslated.length === 0) {
+        return { untranslated: 0, applied: 0, remaining: 0, po: args.poText };
+    }
+    const prompt = (0, prompt_1.buildTranslationPrompt)(args.targetLabel, (0, po_1.serializePo)(untranslated));
+    const reply = await args.translate({
+        prompt,
+        targetLocale: args.targetLocale,
+        targetLabel: args.targetLabel,
+        sourceLocale: args.sourceLocale,
+    });
+    if (typeof reply !== 'string' || reply.trim() === '') {
+        throw new Error(`translator returned an empty reply for ${args.targetLabel}`);
+    }
+    const { po, applied } = (0, apply_1.applyTranslations)(args.poText, reply);
+    const remaining = (0, po_1.parsePo)(po).filter((e) => (0, apply_1.isUntranslated)(e.msgstr)).length;
+    return { untranslated: untranslated.length, applied, remaining, po };
+}
+//# sourceMappingURL=translator.js.map

package/src/lib/translator.js.map

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