@verbatra/sdk 0.8.0 → 0.9.0

package/dist/index.d.ts

@@ -69,10 +69,11 @@ type Tone = "formal" | "informal" | "neutral";
  */
 type PlaceholderExtractor = (value: string) => readonly string[];
 /**
- * Compares a source and translated value's placeholders directly, branch-aware, instead of
- * independently extracting each side's flat placeholder list first. Supplied by the caller (the SDK, for
- * a format whose adapter defines one, for example ICU plural/select) so it matches the entries' format;
- * ai-providers never derives it itself and never parses a specific format's message syntax.
+ * Compares a source and translated value directly instead of independently extracting each side's flat
+ * placeholder list first, which lets it express checks the flat lists cannot (branch-aware ICU
+ * comparison, or a one-directional rule). Supplied by the caller (the SDK, for a format whose adapter
+ * defines one) so it matches the entries' format; ai-providers never derives it itself and never parses
+ * a specific format's message syntax.
  */
 type PlaceholderComparator = (source: string, translated: string) => PlaceholderIntegrityResult$1;
 /**
@@ -94,9 +95,11 @@ interface TranslateRequest {
     /** Mandatory placeholder extractor; the output integrity check runs against it. */
     readonly extractPlaceholders: PlaceholderExtractor;
     /**
-     * Optional branch-aware placeholder comparator. When present, the output integrity check uses it
+     * Optional whole-value placeholder comparator. When present, the output integrity check uses it
      * instead of independently extracting each side's placeholders with {@link extractPlaceholders} and
-     * diffing the flat lists. Absent for a format with no plural/select sub-message structure.
+     * diffing the flat lists. Supplied for a format whose adapter defines one, whether because the
+     * comparison is branch-aware or because it adds a check the flat lists cannot express. Absent
+     * otherwise.
      */
     readonly comparePlaceholders?: PlaceholderComparator;
     /**
@@ -310,11 +313,11 @@ type BoundedBytesRead = {
  * `deps.fs` option redirects that I/O, which is how the SDK's tests avoid touching disk and how an
  * embedding application can back part of a project with something other than a local disk.
  *
- * Know what the seam does and does not cover before relying on it. It carries the run-status file,
- * the lock-file, the config glossary, and workbook and interchange I/O. It does not carry the
- * locale files: those are read and written by `@verbatra/format-adapters`, which uses `node:fs`
- * directly and is given a path rather than this port. Supplying a `deps.fs` therefore does not make
- * a run fully in-memory, and a project's translations are still read from and written to real disk.
+ * The seam carries every file the SDK touches: the run-status file, the lock-file, the config
+ * glossary, workbook and interchange I/O, and the locale files themselves, which the adapters read
+ * and write through a port built from this one. The single exception is a caller-supplied
+ * `deps.adapterRegistry`: those adapters were constructed by the caller, so their file access is
+ * whatever the caller wired into them, and supplying both means the caller owns that wiring.
  *
  * Reads are size-bounded by contract so that a hostile or accidentally huge file cannot exhaust
  * memory. Writes are expected to be atomic: the default implementation writes to a temporary file
@@ -435,12 +438,17 @@ type ProviderId = ProviderConfig["id"];
  * own tooling.
  *
  * The object is strict, so an unrecognized key is an error rather than being silently ignored: a
- * typo in a config file is reported instead of quietly doing nothing. Beyond the per-field checks,
- * three whole-config rules are enforced: `targetLocales` must not contain the source locale, it
- * must not contain two locales that differ only in case (they would collide on a case-insensitive
- * file system), and `files.pattern` must contain the `{locale}` token.
+ * typo in a config file is reported instead of quietly doing nothing. The one exception is the
+ * optional `$schema` key, accepted so a JSON or YAML config can point an editor at the JSON Schema
+ * document the package ships as `@verbatra/sdk/config-schema.json`.
+ *
+ * Beyond the per-field checks, two whole-config rules are enforced: `targetLocales` must not
+ * contain the source locale, and it must not contain two locales that differ only in case (they
+ * would collide on a case-insensitive file system). The `{locale}` token requirement is a
+ * per-field check on `files.pattern`.
  */
 declare const verbatraConfigSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
     sourceLocale: z.ZodString;
     targetLocales: z.ZodArray<z.ZodString>;
     format: z.ZodEnum<{
@@ -682,6 +690,90 @@ type GlossaryProvenance = {
     readonly path: string;
 };
 
+/** Input for {@link readGlossaryFile} and {@link updateGlossaryTerm}. */
+interface GlossaryFileInput {
+    /**
+     * Where the loaded config's glossary came from, as reported by {@link loadConfigWithMeta}. Only a
+     * `file` provenance is accepted; it also carries the path, which is why neither function takes one.
+     */
+    readonly glossary: GlossaryProvenance;
+}
+/** Input for {@link updateGlossaryTerm}. */
+interface UpdateGlossaryTermInput extends GlossaryFileInput {
+    /** Directory the write lock is taken under. Defaults to the process working directory. */
+    readonly cwd?: string;
+    /** The source term to add, replace, or remove. Must not be blank. */
+    readonly term: string;
+    /** The translation to store for the term, or `null` to remove the term. Must not be blank. */
+    readonly translation: string | null;
+}
+/** Injectable dependencies for {@link readGlossaryFile} and {@link updateGlossaryTerm}. */
+interface GlossaryFileDeps {
+    /** File-system port. Defaults to the real file system. */
+    readonly fs?: SdkFs;
+}
+/**
+ * Reads a file-backed glossary fresh from disk, under the same validation {@link loadConfig} applies
+ * when it resolves a glossary path. Use it when a long-running tool has to show the glossary as it
+ * is now rather than as it was when the config was loaded.
+ *
+ * The file to read comes from the provenance itself, so there is no way to point this at a file the
+ * loaded config does not name.
+ *
+ * @param input - The glossary provenance from a loaded config.
+ * @param deps - Optional file-system override.
+ * @returns The glossary as a flat term map.
+ *
+ * @throws {@link SdkError} `GLOSSARY_NOT_FILE_BACKED`: the config's glossary is inline or absent, so
+ * there is no file to read.
+ * @throws {@link SdkError} `CONFIG_INVALID`: the glossary file is missing, oversized, not UTF-8, not
+ * valid JSON, or not a flat object of string keys to string values.
+ */
+declare function readGlossaryFile(input: GlossaryFileInput, deps?: GlossaryFileDeps): Promise<Readonly<Record<string, string>>>;
+/**
+ * Adds, replaces, or removes one term in a file-backed glossary, rewriting the JSON file in place.
+ * This is the write path behind a glossary editor: one term changes and the rest of the file keeps
+ * its order and its indentation.
+ *
+ * Only a file-backed glossary can be edited. An inline glossary lives inside the config module,
+ * which is executable code this function will not rewrite, and no glossary at all has no file to
+ * write to; both are refused rather than converted.
+ *
+ * The whole read-modify-write runs under a project-wide glossary lock, so two concurrent edits are
+ * serialized rather than interleaved, and the file itself is replaced atomically. The result is
+ * validated to stay within the same size limit {@link loadConfig} enforces when it reads a glossary
+ * file back, so an accepted write is always re-readable.
+ *
+ * @param input - The glossary provenance, the term, and its new translation or `null` to remove it.
+ * @param deps - Optional file-system override.
+ * @returns The glossary as it now stands on disk.
+ *
+ * @throws {@link SdkError} `GLOSSARY_NOT_FILE_BACKED`: the config's glossary is inline or absent, so
+ * there is no file to write.
+ * @throws {@link SdkError} `CONFIG_INVALID`: the term or its translation is blank, the glossary file
+ * on disk is missing, oversized, not UTF-8, not valid JSON, or not a flat object of string keys to
+ * string values, or the updated glossary would exceed the maximum glossary file size.
+ * @throws {@link SdkError} `LOCK_CONTENDED`: the project's glossary write lock could not be acquired
+ * before the timeout elapsed.
+ * @throws {@link SdkError} `GLOSSARY_UNWRITABLE`: the glossary file could not be written.
+ *
+ * @example
+ * ```ts
+ * import { loadConfigWithMeta, updateGlossaryTerm } from "@verbatra/sdk";
+ *
+ * const loaded = await loadConfigWithMeta({ cwd: process.cwd() });
+ * const glossary = await updateGlossaryTerm({
+ *   glossary: loaded.glossary,
+ *   cwd: process.cwd(),
+ *   term: "Verbatra",
+ *   translation: "Verbatra",
+ * });
+ *
+ * console.log(Object.keys(glossary).length);
+ * ```
+ */
+declare function updateGlossaryTerm(input: UpdateGlossaryTermInput, deps?: GlossaryFileDeps): Promise<Readonly<Record<string, string>>>;
+
 /** Options for {@link loadConfig} and {@link loadConfigWithMeta}. */
 interface LoadConfigOptions {
     /** Directory to search from, and the base for relative paths. Defaults to the process working directory. */
@@ -782,18 +874,25 @@ declare function loadConfig(options?: LoadConfigOptions): Promise<VerbatraConfig
  * wraps them.
  *
  * - `CONFIG_NOT_FOUND`: no config file was found by search, or an explicit `configPath` does not
- *   exist. Thrown by {@link loadConfig} and {@link loadConfigWithMeta}.
+ *   exist. Thrown by {@link loadConfig} and {@link loadConfigWithMeta}. {@link doctor} narrows it
+ *   to the explicit-path case: a config that is only absent from the search is reported as a failed
+ *   check instead, since reporting that is the command's job.
  * - `CONFIG_INVALID`: a config was found but is unparseable or fails validation, or its glossary
  *   file could not be resolved or parsed. Thrown by {@link loadConfig} and
- *   {@link loadConfigWithMeta}. {@link importWorkbook} does not throw it: when a handoff sheet or
- *   file names a locale that is not a configured target locale, it records this code on that
- *   locale's {@link LocaleSummary} instead.
+ *   {@link loadConfigWithMeta}, by {@link readGlossaryFile}, and by {@link updateGlossaryTerm},
+ *   which additionally throws it for a blank term or translation and for an edit whose result would
+ *   exceed the glossary file size limit. {@link importWorkbook} does not throw it: when a handoff
+ *   sheet or file names a locale that is not a configured target locale, it records this code on
+ *   that locale's {@link LocaleSummary} instead.
  * - `UNKNOWN_FORMAT`: no adapter is registered for the configured format. Thrown by every entry
- *   point that selects an adapter, before any file is read.
+ *   point that selects an adapter, before any file is read. {@link doctor} is the exception: it
+ *   reports an unresolvable format as a failed `format-adapter` check instead, since reporting that
+ *   is the command's job.
  * - `UNKNOWN_LOCALE`: a requested locale is not among the configured target locales. Thrown through
- *   the shared locale selection by {@link check}, {@link diff}, {@link keyIntegrity},
- *   {@link lockState}, {@link exportWorkbook}, {@link keyValue}, {@link editEntry}, and
- *   {@link retranslateEntry}.
+ *   the shared locale selection by {@link translate}, {@link watch}, {@link check}, {@link diff},
+ *   {@link keyIntegrity}, {@link lockState}, {@link exportWorkbook}, {@link keyValue},
+ *   {@link editEntry}, and {@link retranslateEntry}. {@link translate} throws it before anything is
+ *   read or spent, and {@link watch} once at startup, before any watching begins.
  * - `UNKNOWN_KEY`: the requested key is not present in the source resource. Thrown by
  *   {@link keyValue}, {@link editEntry}, and {@link retranslateEntry}.
  * - `PROVIDER_CONSTRUCTION_FAILED`: the provider factory threw. Wraps the provider's own error,
@@ -809,15 +908,24 @@ declare function loadConfig(options?: LoadConfigOptions): Promise<VerbatraConfig
  *   {@link diff}, {@link keyIntegrity}, {@link lockState}, {@link loadLockFile},
  *   {@link exportWorkbook}, {@link importWorkbook}, {@link editEntry}, and
  *   {@link retranslateEntry}.
- * - `LOCK_CONTENDED`: a locale's write lock could not be acquired before its timeout elapsed,
- *   because another process holds it or a killed process left the lock file behind. The message
+ * - `LOCK_CONTENDED`: a write lock could not be acquired before its timeout elapsed, because
+ *   another process holds it or a killed process left the lock file behind. The message
  *   names the lock file's path. Thrown by {@link editEntry} and {@link retranslateEntry}, which
- *   act on one locale. {@link translate} and {@link importWorkbook} do not throw it: they record it
+ *   act on one locale, and by {@link updateGlossaryTerm}, which takes the project's glossary lock.
+ *   {@link translate} and {@link importWorkbook} do not throw it: they record it
  *   on the contended locale's {@link LocaleSummary} and carry on with the other locales.
+ * - `GLOSSARY_NOT_FILE_BACKED`: the loaded config's glossary is written inline or absent, so there
+ *   is no glossary file to read or rewrite. Thrown by {@link readGlossaryFile} and
+ *   {@link updateGlossaryTerm}, which work on a file-backed glossary alone and never rewrite the
+ *   config module itself.
+ * - `GLOSSARY_UNWRITABLE`: the glossary file could not be written, because it or its directory is
+ *   read-only, has been removed, or the disk is out of space. Thrown by
+ *   {@link updateGlossaryTerm}.
  * - `LOCALE_LAYOUT_INVALID`: the configured `files.pattern` and `files.localeStyle` cannot be
  *   combined, or the style has no valid path spelling for a configured locale. Thrown by
  *   {@link createLocalePathResolver}, and so by every entry point that maps a locale to a path,
- *   before any file is read and before any provider call.
+ *   before any file is read and before any provider call. {@link doctor} is the exception: it
+ *   reports the resolver's failure as a failed `source-file` check instead.
  * - `LOCALE_PATH_COLLISION`: two configured locales resolve to the same absolute path, which would
  *   make the path-to-locale direction ambiguous and let two locale workers race on one file. Thrown
  *   at the same point as `LOCALE_LAYOUT_INVALID`.
@@ -827,10 +935,16 @@ declare function loadConfig(options?: LoadConfigOptions): Promise<VerbatraConfig
  * - `CONCURRENCY_BUDGET_CONFLICT`: a live run requested a `concurrency` above 1 while a token
  *   budget is configured. The two are mutually exclusive because concurrency makes the budget's
  *   stop guarantee nondeterministic. A dry run is exempt, since it never consults the budget.
+ * - `TARGET_UNWRITABLE`: a target locale file could not be written, because its directory is not
+ *   writable, does not exist, is read-only, or is out of space. The message names the target file
+ *   relative to `cwd` and the underlying file-system code, never the internal temporary file the
+ *   atomic write uses. Thrown by {@link editEntry} and {@link retranslateEntry}, which act on one
+ *   locale. {@link translate} and {@link importWorkbook} do not throw it: they record it on that
+ *   locale's {@link LocaleSummary} and carry on with the other locales.
  * - `LOCALE_FAILED`: never thrown. It is the fallback code recorded on a failed
  *   {@link LocaleSummary} when a per-locale failure carries no code of its own.
  */
-type SdkErrorCode = "CONFIG_NOT_FOUND" | "CONFIG_INVALID" | "UNKNOWN_FORMAT" | "UNKNOWN_LOCALE" | "UNKNOWN_KEY" | "PROVIDER_CONSTRUCTION_FAILED" | "SOURCE_UNREADABLE" | "SOURCE_INVALID" | "LOCK_FILE_INVALID" | "LOCK_CONTENDED" | "LOCALE_LAYOUT_INVALID" | "LOCALE_PATH_COLLISION" | "CONCURRENCY_INVALID" | "CONCURRENCY_BUDGET_CONFLICT" | "LOCALE_FAILED";
+type SdkErrorCode = "CONFIG_NOT_FOUND" | "CONFIG_INVALID" | "UNKNOWN_FORMAT" | "UNKNOWN_LOCALE" | "UNKNOWN_KEY" | "PROVIDER_CONSTRUCTION_FAILED" | "SOURCE_UNREADABLE" | "SOURCE_INVALID" | "LOCK_FILE_INVALID" | "LOCK_CONTENDED" | "GLOSSARY_NOT_FILE_BACKED" | "GLOSSARY_UNWRITABLE" | "LOCALE_LAYOUT_INVALID" | "LOCALE_PATH_COLLISION" | "CONCURRENCY_INVALID" | "CONCURRENCY_BUDGET_CONFLICT" | "TARGET_UNWRITABLE" | "LOCALE_FAILED";
 /**
  * The single structured error the SDK throws. Every whole-run failure surfaces as an `SdkError`
  * carrying a stable {@link SdkErrorCode}; per-locale failures, provider notices, and integrity
@@ -1016,15 +1130,24 @@ interface FormatAdapter {
      */
     validateMessage(value: string): boolean;
     /**
-     * Optional branch-aware placeholder comparison for formats with plural/select sub-message structure.
-     * When present, callers use it instead of independently extracting each side's placeholders with
-     * {@link extractPlaceholders} and diffing the flat lists, since flattening a plural/select value loses
-     * which branch a placeholder came from. Absent for every non-ICU adapter, which is compared via
-     * `extractPlaceholders` plus a flat multiset check as before.
+     * Optional whole-value placeholder comparison, used by callers instead of independently extracting
+     * each side's placeholders with {@link extractPlaceholders} and diffing the flat lists. Two adapter
+     * families define one, for different reasons:
+     *
+     * - The ICU formats (next-intl and ARB) compare branch by branch, because flattening a
+     *   plural/select value loses which branch a placeholder came from.
+     * - The double-brace formats (i18next, ngx-translate, and YAML) add a one-directional
+     *   single-brace check on top of their flat multiset comparison: a `{name}`-shaped token present
+     *   in the translated value but absent from the source is reported as `extra`. Single-brace text
+     *   is ordinary literal content under these formats' default delimiters, so it is never required
+     *   to survive a translation, but inventing one is never a legitimate translation either.
+     *
+     * Absent for the remaining adapters, which are compared via `extractPlaceholders` plus a flat
+     * multiset check.
      *
      * @param sourceValue - The source value.
      * @param targetValue - The translated value to check against it.
-     * @returns The merged placeholder-integrity result across every branch. Does not throw.
+     * @returns The merged placeholder-integrity result. Does not throw.
      */
     comparePlaceholders?(sourceValue: string, targetValue: string): PlaceholderIntegrityResult;
 }
@@ -1146,9 +1269,10 @@ interface CheckDeps {
  *
  * Use {@link diff} instead when you need the key names rather than the counts.
  *
- * Note that a malformed target locale file surfaces the adapter's own parse error rather than a
- * wrapped {@link SdkError}, because only source reads are wrapped. A caller that maps SDK codes
- * should be ready for an unrecognized error from a target file.
+ * Note that a malformed target locale file surfaces the adapter's own error and code rather than a
+ * wrapped {@link SdkError}, because only source reads are wrapped. Its message names the offending
+ * locale and the resolved path. A caller that maps SDK codes should be ready for an unrecognized
+ * error from a target file.
  *
  * @param input - The config and the optional locale filter.
  * @param deps - Optional adapter registry and file-system overrides.
@@ -1217,9 +1341,10 @@ interface DiffDeps {
  * since the key was last translated rather than merely that the two strings differ. Orphaned keys
  * are reported but never removed here; pruning happens only in {@link translate}.
  *
- * Note that a malformed target locale file surfaces the adapter's own parse error rather than a
- * wrapped {@link SdkError}, because only source reads are wrapped. A caller that maps SDK codes
- * should be ready for an unrecognized error from a target file.
+ * Note that a malformed target locale file surfaces the adapter's own error and code rather than a
+ * wrapped {@link SdkError}, because only source reads are wrapped. Its message names the offending
+ * locale and the resolved path. A caller that maps SDK codes should be ready for an unrecognized
+ * error from a target file.
  *
  * @param input - The config and the optional locale filter.
  * @param deps - Optional adapter registry and file-system overrides.
@@ -1237,6 +1362,115 @@ interface DiffDeps {
  */
 declare function diff(input: DiffInput, deps?: DiffDeps): Promise<DiffSummary>;
 
+/**
+ * Which project-setup question a {@link DoctorCheck} answers.
+ *
+ * - `config`: a config file was found and passes validation.
+ * - `format-adapter`: the configured `format` resolves to a file adapter.
+ * - `provider`: the configured `provider.id` resolves to a provider factory.
+ * - `api-key`: the environment variable the configured provider reads its key from is set.
+ * - `source-file`: the source locale file exists at its resolved path, is a regular file, and
+ *   parses under the configured format.
+ */
+type DoctorCheckId = "config" | "format-adapter" | "provider" | "api-key" | "source-file";
+/**
+ * The verdict on one {@link DoctorCheck}. `skipped` is reported only for the checks that need a
+ * loaded config when the `config` check itself failed, so a skipped check is never a problem of its
+ * own.
+ */
+type DoctorCheckStatus = "pass" | "fail" | "skipped";
+/** One project-setup question and its verdict. */
+interface DoctorCheck {
+    /** Which question this check answers. */
+    readonly id: DoctorCheckId;
+    /** A short human-readable name for the check, stable across runs. */
+    readonly title: string;
+    /** The verdict. Only `fail` makes {@link DoctorResult.ok} false. */
+    readonly status: DoctorCheckStatus;
+    /**
+     * Why the check reached its verdict. On a failure this carries the underlying error message
+     * verbatim, so a config validation problem reads exactly as {@link loadConfig} words it. It names
+     * environment variables and paths, never an API key value.
+     */
+    readonly detail: string;
+}
+/** The result of {@link doctor}: every check that ran, and one project-wide verdict. */
+interface DoctorResult {
+    /** True only when no check failed. This is the value a script should branch on. */
+    readonly ok: boolean;
+    /** Every check, always in the same order, one entry per {@link DoctorCheckId}. */
+    readonly checks: readonly DoctorCheck[];
+}
+/** Input for {@link doctor}. */
+interface DoctorInput {
+    /** Directory to search the config from, and the base for locale paths. Defaults to the process working directory. */
+    readonly cwd?: string;
+    /** An explicit config file to validate, bypassing the search. A missing file is an error rather than a failed check. */
+    readonly configPath?: string;
+}
+/** Injectable dependencies for {@link doctor}. Every field has a working default. */
+interface DoctorDeps {
+    /** Format-adapter registry to resolve the configured format against. Defaults to the built-in registry. */
+    readonly adapterRegistry?: AdapterRegistry;
+    /**
+     * File-system port. Threaded into the config loader, so it backs the glossary-file read the
+     * `config` check performs, and used to read and parse the source locale file. Defaults to the
+     * real file system.
+     */
+    readonly fs?: SdkFs;
+    /** Config loader. Defaults to {@link loadConfigWithMeta}. */
+    readonly loadConfig?: (options: LoadConfigOptions) => Promise<LoadedConfig>;
+}
+/**
+ * Validates a project's setup and spends nothing: no provider is constructed, no network request is
+ * made, and no file is written. Run it before {@link translate} on a fresh project, or when a run
+ * failed and you want the whole list of problems rather than the first one.
+ *
+ * Five checks run: the config loads and validates, the configured format resolves to an adapter,
+ * the configured provider ID resolves to a factory, the environment variable that provider reads
+ * its API key from is set, and the source locale file can be read. Every check runs even when an
+ * earlier one failed, so one call reports every independent problem. The API key is checked by
+ * variable name only: its value is never read, never returned, and never validated against a
+ * provider.
+ *
+ * The source-file check reads and parses the file rather than only probing for its existence, so a
+ * directory standing in for it, an empty file, and malformed content are all reported here rather
+ * than surfacing later as a whole-run failure of {@link check} or {@link translate}. The failure
+ * detail is the same message those entry points raise. When the configured format resolves to no
+ * adapter there is nothing to parse with, so the check falls back to existence alone and says so.
+ *
+ * The `openai-compatible` provider is the one exception on the key check. It falls back to a
+ * placeholder key, so a missing variable passes unless the config names its own variable through
+ * `provider.options.apiKeyEnvVar`, which then has to be set.
+ *
+ * A target locale file is not checked at all: a missing one is not a problem, because
+ * {@link translate} creates it. The source locale file is checked, because every other entry point
+ * fails on it.
+ *
+ * When the config cannot be loaded the four config-dependent checks report `skipped` rather than a
+ * verdict they could not reach, and {@link DoctorResult.ok} is false because the config check
+ * itself failed.
+ *
+ * @param input - The working directory and an optional explicit config path.
+ * @param deps - Optional adapter registry, file-system, and config-loader overrides.
+ * @returns Every check with its verdict, and the project-wide `ok` verdict.
+ *
+ * @throws {@link SdkError} `CONFIG_NOT_FOUND`: an explicit `configPath` was given and no file
+ * exists there. A config that is merely absent from the search is a failed check instead.
+ *
+ * @example
+ * ```ts
+ * import { doctor } from "@verbatra/sdk";
+ *
+ * const report = await doctor();
+ * for (const check of report.checks) {
+ *   console.log(`${check.status}: ${check.title} - ${check.detail}`);
+ * }
+ * process.exitCode = report.ok ? 0 : 1;
+ * ```
+ */
+declare function doctor(input?: DoctorInput, deps?: DoctorDeps): Promise<DoctorResult>;
+
 /**
  * Why a candidate translation was refused before it could be written. The same gate guards
  * {@link editEntry} and {@link retranslateEntry}, so a hand-typed value and a provider-produced one
@@ -1246,7 +1480,9 @@ declare function diff(input: DiffInput, deps?: DiffDeps): Promise<DiffSummary>;
  * previous translation stays intact.
  *
  * - `placeholder`: the candidate does not carry the same placeholders as the source, so
- *   interpolation would break at runtime.
+ *   interpolation would break at runtime. For the double-brace formats (i18next, ngx-translate, and
+ *   YAML) this also covers a single-brace `{name}`-shaped token the candidate invented and the
+ *   source never had, which is a fabrication whichever interpolation delimiters the project uses.
  * - `icu`: the candidate is not a valid ICU message under the configured format's adapter.
  * - `degenerate`: the candidate collapsed into runaway output rather than a translation. Two shapes
  *   are detected: the candidate is at least twelve times the length of a source of meaningful
@@ -1311,9 +1547,14 @@ type EditEntryResult = {
  * and feeds the translation memory, which means a later run treats the key as up to date and
  * reuses the edited text rather than paying the provider to translate it again.
  *
- * Note that a malformed target locale file surfaces the adapter's own parse error rather than a
- * wrapped {@link SdkError}, because only source reads are wrapped. A caller that maps SDK codes
- * should be ready for an unrecognized error from a target file.
+ * Note that the target locale file surfaces the adapter's own error and code rather than a wrapped
+ * {@link SdkError}, on the write as well as on the read, because only the source read is wrapped.
+ * A malformed target file fails the read with a message naming the offending locale and the
+ * resolved path. The write raises the adapter's error too, when the entries cannot be represented
+ * in the configured format or the existing destination file cannot be read back to be updated in
+ * place, and that error is re-thrown unchanged so its own code survives for a caller that maps
+ * adapter codes to its own copy. A caller that maps SDK codes should be ready for an unrecognized
+ * error from a target file on either path.
  *
  * @param input - The config, locale, key, and new value.
  * @param deps - Optional adapter registry and file-system overrides.
@@ -1329,8 +1570,14 @@ type EditEntryResult = {
  * @throws {@link SdkError} `UNKNOWN_KEY`: the key is not present in the source resource.
  * @throws {@link SdkError} `LOCK_CONTENDED`: the locale's write lock could not be acquired before
  * the timeout elapsed.
+ * @throws {@link SdkError} `TARGET_UNWRITABLE`: the target locale file could not be written because
+ * of a file-system failure. The message names the target file and the file-system code, never the
+ * internal temporary file.
  * @throws {@link SdkError} `LOCK_FILE_INVALID`: the lock-file is corrupt, oversized, or at an
  * unsupported version.
+ * @throws `AdapterError`: the adapter itself refused the target locale file, on the read because it
+ * is malformed or on the write because the entries cannot be represented in the configured format.
+ * Its own code is preserved rather than remapped onto an {@link SdkErrorCode}.
  */
 declare function editEntry(input: EditEntryInput, deps?: EditEntryDeps): Promise<EditEntryResult>;
 
@@ -1387,9 +1634,10 @@ interface KeyIntegrityDeps {
  * {@link retranslateEntry} enforce at write time, and the data behind a review dashboard's
  * per-key integrity indicator.
  *
- * Note that a malformed target locale file surfaces the adapter's own parse error rather than a
- * wrapped {@link SdkError}, because only source reads are wrapped. A caller that maps SDK codes
- * should be ready for an unrecognized error from a target file.
+ * Note that a malformed target locale file surfaces the adapter's own error and code rather than a
+ * wrapped {@link SdkError}, because only source reads are wrapped. Its message names the offending
+ * locale and the resolved path. A caller that maps SDK codes should be ready for an unrecognized
+ * error from a target file.
  *
  * @param input - The config and the optional locale and key filters.
  * @param deps - Optional adapter registry and file-system overrides.
@@ -1441,9 +1689,10 @@ interface KeyValueResult {
  * cannot be edited or retranslated, while a key absent from the target is normal and simply comes
  * back with no `target`.
  *
- * Note that a malformed target locale file surfaces the adapter's own parse error rather than a
- * wrapped {@link SdkError}, because only source reads are wrapped. A caller that maps SDK codes
- * should be ready for an unrecognized error from a target file.
+ * Note that a malformed target locale file surfaces the adapter's own error and code rather than a
+ * wrapped {@link SdkError}, because only source reads are wrapped. Its message names the offending
+ * locale and the resolved path. A caller that maps SDK codes should be ready for an unrecognized
+ * error from a target file.
  *
  * @param input - The config, locale, and key to read.
  * @param deps - Optional adapter registry and file-system overrides.
@@ -1499,8 +1748,9 @@ interface ReadLocaleFileSnapshotDeps {
  * watcher can start before the first translation run has written anything.
  *
  * Note that this entry point does not validate the locale against the configured targets, and that
- * a malformed target file surfaces the adapter's own parse error rather than a wrapped
- * {@link SdkError}, because no source-file contract is being asserted here.
+ * a malformed target file surfaces the adapter's own error and code rather than a wrapped
+ * {@link SdkError}, because no source-file contract is being asserted here. Its message names the
+ * offending locale and the resolved path.
  *
  * @param input - The config and the locale to snapshot.
  * @param deps - Optional adapter registry and file-system overrides.
@@ -1591,9 +1841,10 @@ interface LockStateDeps {
  * When no lock-file exists the call returns `exists: false` rather than throwing, and does no
  * further reading.
  *
- * Note that a malformed target locale file surfaces the adapter's own parse error rather than a
- * wrapped {@link SdkError}, because only source reads are wrapped. A caller that maps SDK codes
- * should be ready for an unrecognized error from a target file.
+ * Note that a malformed target locale file surfaces the adapter's own error and code rather than a
+ * wrapped {@link SdkError}, because only source reads are wrapped. Its message names the offending
+ * locale and the resolved path. A caller that maps SDK codes should be ready for an unrecognized
+ * error from a target file.
  *
  * @param input - The config and the optional locale filter.
  * @param deps - Optional adapter registry and file-system overrides.
@@ -1681,9 +1932,14 @@ type RetranslateEntryResult = {
  * baseline and feeds the translation memory, so a later {@link translate} run sees the key as up
  * to date.
  *
- * Note that a malformed target locale file surfaces the adapter's own parse error rather than a
- * wrapped {@link SdkError}, because only source reads are wrapped. A caller that maps SDK codes
- * should be ready for an unrecognized error from a target file.
+ * Note that the target locale file surfaces the adapter's own error and code rather than a wrapped
+ * {@link SdkError}, on the write as well as on the read, because only the source read is wrapped.
+ * A malformed target file fails the read with a message naming the offending locale and the
+ * resolved path. The write raises the adapter's error too, when the entries cannot be represented
+ * in the configured format or the existing destination file cannot be read back to be updated in
+ * place, and that error is re-thrown unchanged so its own code survives for a caller that maps
+ * adapter codes to its own copy. A caller that maps SDK codes should be ready for an unrecognized
+ * error from a target file on either path.
  *
  * @param input - The config, locale, and key to retranslate.
  * @param deps - Optional adapter registry, provider factory, and file-system overrides.
@@ -1701,8 +1957,14 @@ type RetranslateEntryResult = {
  * most often because its API key environment variable is unset.
  * @throws {@link SdkError} `LOCK_CONTENDED`: the locale's write lock could not be acquired before
  * the timeout elapsed.
+ * @throws {@link SdkError} `TARGET_UNWRITABLE`: the target locale file could not be written because
+ * of a file-system failure. The message names the target file and the file-system code, never the
+ * internal temporary file.
  * @throws {@link SdkError} `LOCK_FILE_INVALID`: the lock-file is corrupt, oversized, or at an
  * unsupported version.
+ * @throws `AdapterError`: the adapter itself refused the target locale file, on the read because it
+ * is malformed or on the write because the entries cannot be represented in the configured format.
+ * Its own code is preserved rather than remapped onto an {@link SdkErrorCode}.
  * @throws `ProviderError` `INVALID_RESPONSE`: the provider returned no value for the key. Provider
  * transport and rate-limit failures propagate as `ProviderError` too, since a single-key call has
  * no per-locale summary to record them on.
@@ -1884,11 +2146,21 @@ interface LocaleSummary {
 interface RunSummary {
     /** True when the run computed everything but wrote nothing and called no provider. */
     readonly dryRun: boolean;
-    /** The full per-locale account, in configured target order. */
+    /**
+     * The full per-locale account. A {@link translate} or {@link watch} run reports them in
+     * configured target order, whatever order a `locales` subset was given in and whatever order
+     * concurrent locales finished in. An {@link importWorkbook} run does not: it reports them in the
+     * order the handoff yielded them, then appends the configured locales the handoff had nothing
+     * for. Match an entry on its `locale` rather than on its position.
+     */
     readonly locales: readonly LocaleSummary[];
     /** Names of the locales whose status is `succeeded`. */
     readonly succeeded: readonly string[];
-    /** Names of the locales whose status is `partial`. */
+    /**
+     * Names of the locales whose status is `partial`: written to disk, but with keys still missing.
+     * Check this alongside `failed` before treating a run as clean. The CLI exits `1` on a partial
+     * locale for that reason.
+     */
     readonly partial: readonly string[];
     /** Names of the locales whose status is `failed`. Check this before treating a run as clean. */
     readonly failed: readonly string[];
@@ -1965,8 +2237,9 @@ type RunStatusResult = {
  * anything.
  *
  * The read is deliberately total: a missing, oversized, unparseable, schema-invalid, or
- * wrong-version file all report `available: false` rather than throwing, because stale local status
- * should never break the tool reading it. This call throws nothing.
+ * wrong-version file all report `available: false` rather than throwing, and so does an injected
+ * `deps.fs` whose read rejects, because stale or unreachable local status should never break the
+ * tool reading it. This call throws nothing.
  *
  * @param input - The optional working directory.
  * @param deps - Optional file-system override.
@@ -2075,6 +2348,18 @@ interface TranslateInput {
     readonly config: VerbatraConfig;
     /** Directory the `files.pattern` is resolved against. Defaults to the process working directory. */
     readonly cwd?: string;
+    /**
+     * Restrict the run to a subset of the configured target locales, which is how you translate one
+     * locale at a time against a rate-limited provider. Defaults to every configured target. The
+     * result keeps the configured order whatever order the subset is given in, and any locale named
+     * here that is not a configured target fails the whole run with `UNKNOWN_LOCALE` before anything
+     * is read or spent. An explicit empty array selects no locale at all rather than every locale.
+     *
+     * Locales left out are untouched: their files, their lock entries, and their translation-memory
+     * entries all stay as they were. The run-status file always describes the most recent run alone,
+     * so a subset run narrows it to that subset.
+     */
+    readonly locales?: readonly string[];
     /**
      * Compute the whole run but write nothing and call no provider. The returned
      * {@link RunSummary} reports what would have happened, which makes this safe to run in CI to
@@ -2122,7 +2407,8 @@ interface TranslateDeps {
     readonly fs?: SdkFs;
 }
 /**
- * Runs the one-shot translation flow over every configured target locale: read the source, diff
+ * Runs the one-shot translation flow over every configured target locale, or over the subset named
+ * by `locales`: read the source, diff
  * each locale against the lock-file baseline, translate what is missing or stale, verify placeholder
  * and ICU integrity, write the locale files, and update the lock-file and translation memory.
  *
@@ -2132,8 +2418,10 @@ interface TranslateDeps {
  * {@link LocaleSummary} and the other locales continue, so one unreachable provider or one
  * unwritable file never discards work that succeeded. A locale whose write lock stays contended is
  * one of these per-locale failures: it is recorded with code `LOCK_CONTENDED` on that locale's
- * summary rather than thrown. Callers should therefore inspect {@link RunSummary.failed} rather
- * than relying on a thrown error to detect trouble.
+ * summary rather than thrown. Callers should therefore inspect {@link RunSummary.failed} and
+ * {@link RunSummary.partial} rather than relying on a thrown error to detect trouble. A partial
+ * locale is a locale whose file was written with some keys missing, so treating it as clean would
+ * ship an incomplete translation; the CLI exits `1` for it exactly as it does for a failed one.
  *
  * A corrupt lock-file is the one exception. On a live run each locale reads the lock-file inside
  * its own write lock, so `LOCK_FILE_INVALID` escapes as a thrown error even after earlier locales
@@ -2150,6 +2438,8 @@ interface TranslateDeps {
  * @param deps - Optional adapter registry, provider factory, and file-system overrides.
  * @returns The per-locale account of the run, including usage and budget.
  *
+ * @throws {@link SdkError} `UNKNOWN_LOCALE`: `locales` names a locale that is not a configured
+ * target. Thrown before anything is read, written, or spent.
  * @throws {@link SdkError} `UNKNOWN_FORMAT`: no adapter is registered for the configured format.
  * @throws {@link SdkError} `CONCURRENCY_INVALID`: `concurrency` is not an integer of at least 1.
  * @throws {@link SdkError} `CONCURRENCY_BUDGET_CONFLICT`: a live run combined a `concurrency` above
@@ -2180,9 +2470,9 @@ interface TranslateDeps {
  *   },
  * });
  *
- * if (summary.failed.length > 0) {
- *   for (const locale of summary.locales.filter((entry) => entry.status === "failed")) {
- *     console.error(`${locale.locale}: ${locale.error?.message}`);
+ * if (summary.failed.length > 0 || summary.partial.length > 0) {
+ *   for (const locale of summary.locales.filter((entry) => entry.status !== "succeeded")) {
+ *     console.error(`${locale.locale}: ${locale.status} ${locale.error?.message ?? ""}`);
  *   }
  *   process.exitCode = 1;
  * }
@@ -2280,9 +2570,14 @@ interface ExportWorkbookResult {
  * through the same diff, lock, and integrity checks. It writes only the handoff file and never
  * touches the locale files or the lock-file.
  *
- * Note that a malformed target locale file surfaces the adapter's own parse error rather than a
- * wrapped {@link SdkError}, because only source reads are wrapped. A caller that maps SDK codes
- * should be ready for an unrecognized error from a target file.
+ * Note that a malformed target locale file surfaces the adapter's own error and code rather than a
+ * wrapped {@link SdkError}, because only source reads are wrapped. Its message names the offending
+ * locale and the resolved path. A caller that maps SDK codes should be ready for an unrecognized
+ * error from a target file.
+ *
+ * Writing the handoff itself is unwrapped in the same way. It is not a locale file, so a failure to
+ * create the output directory or to write the file does not become `TARGET_UNWRITABLE`; the
+ * underlying file-system error propagates as it is.
  *
  * @param input - The config, output path, locale filter, and handoff format.
  * @param deps - Optional adapter registry and file-system overrides.
@@ -2297,6 +2592,10 @@ interface ExportWorkbookResult {
  * @throws {@link SdkError} `LOCK_FILE_INVALID`: the lock-file is corrupt, oversized, or at an
  * unsupported version.
  * @throws {@link SdkError} `UNKNOWN_LOCALE`: a requested locale is not a configured target locale.
+ * @throws The underlying file-system error, unwrapped, when the handoff could not be written: `out`
+ * names a directory that does not exist or is not writable, or the device is full. Branch on the
+ * Node `code`, such as `ENOENT`, rather than on the message, which can name the internal temporary
+ * file the atomic write uses.
  */
 declare function exportWorkbook(input: ExportWorkbookInput, deps?: ExportWorkbookDeps): Promise<ExportWorkbookResult>;
 
@@ -2346,7 +2645,10 @@ interface ImportWorkbookDeps {
  * that is not configured is contained the same way: that locale fails with `CONFIG_INVALID` on its
  * own {@link LocaleSummary}, so nothing is written to an unmanaged path and the configured locales
  * still import. Once the handoff has been read, every per-locale failure is isolated this way, so
- * callers should inspect {@link RunSummary.failed} rather than relying on a thrown error.
+ * callers should inspect {@link RunSummary.failed} and {@link RunSummary.partial} rather than
+ * relying on a thrown error. A corrupt lock-file is the one exception, because it is a single
+ * shared file rather than a per-locale one: it aborts the whole run even when it is discovered
+ * after a locale has been applied, so the locales still to come are not written at all.
  *
  * @param input - The config and the handoff path, format, and dry-run flag.
  * @param deps - Optional adapter registry and file-system overrides.
@@ -2361,7 +2663,8 @@ interface ImportWorkbookDeps {
  * cannot be combined, or a configured locale has no valid path spelling under that style.
  * @throws {@link SdkError} `LOCALE_PATH_COLLISION`: two configured locales resolve to the same path.
  * @throws {@link SdkError} `LOCK_FILE_INVALID`: the lock-file is corrupt, oversized, or at an
- * unsupported version. Read once before any locale is applied.
+ * unsupported version. Read before any locale is applied, and re-read as each locale's entries are
+ * recorded, so a lock-file that turns corrupt mid-run aborts the run rather than failing one locale.
  */
 declare function importWorkbook(input: ImportWorkbookInput, deps?: ImportWorkbookDeps): Promise<RunSummary>;
 
@@ -2576,6 +2879,12 @@ interface WatchInput {
     readonly config: VerbatraConfig;
     /** Directory the `files.pattern` is resolved against. Defaults to the process working directory. */
     readonly cwd?: string;
+    /**
+     * Restrict every run of the session to a subset of the configured target locales. Validated once
+     * when watching starts, so an unconfigured locale throws `UNKNOWN_LOCALE` before any watching
+     * begins rather than failing on each run. An explicit empty array selects no locale at all.
+     */
+    readonly locales?: readonly string[];
     /** How long to coalesce rapid source changes before running. Defaults to 300 milliseconds. */
     readonly debounceMs?: number;
     /**
@@ -2624,7 +2933,8 @@ interface WatchController {
  * The returned promise resolves as soon as watching is established, not when translation finishes,
  * so every run outcome arrives through `onRun`. A run that throws is delivered as a failed
  * {@link WatchRunResult} rather than escaping the session, because a watcher that died on the first
- * bad save would be useless. Only startup problems, validated before any watching begins, throw.
+ * bad save would be useless. Only startup problems throw: the inputs validated before any watching
+ * begins, and a failure to construct the watcher itself.
  *
  * Rapid saves are coalesced by `debounceMs`, and runs never overlap, so an editor writing a file
  * several times in a moment produces one run rather than a queue of them.
@@ -2635,6 +2945,8 @@ interface WatchController {
  * @param deps - Optional adapter registry, provider factory, file-system, watcher, and runner overrides.
  * @returns A controller that stops the session.
  *
+ * @throws {@link SdkError} `UNKNOWN_LOCALE`: `locales` names a locale that is not a configured
+ * target. Thrown once at startup, before any watching begins.
  * @throws {@link SdkError} `CONCURRENCY_INVALID`: `concurrency` is not an integer of at least 1.
  * @throws {@link SdkError} `CONCURRENCY_BUDGET_CONFLICT`: `concurrency` above 1 was combined with a
  * configured token budget.
@@ -2643,6 +2955,9 @@ interface WatchController {
  * @throws {@link SdkError} `LOCALE_PATH_COLLISION`: two configured locales resolve to the same path.
  * @throws {@link SdkError} `SOURCE_UNREADABLE`: the source locale file does not exist when watching
  * starts.
+ * @throws Whatever the watcher factory raised, unwrapped, when it could not build a watcher over
+ * the source file. It is not wrapped as an {@link SdkError}. No run has started at that point, so
+ * nothing is watched and `onRun` is never called.
  *
  * @example
  * ```ts
@@ -2665,4 +2980,4 @@ interface WatchController {
  */
 declare function watch(input: WatchInput, deps?: WatchDeps): Promise<WatchController>;
 
-export { type BudgetBehavior, CACHE_FILE_NAME, type CheckDeps, type CheckInput, type CheckSummary, type ConfigSource, type CreateProvider, type CreateWatcher, DEFAULT_DELIMITED_PATH, DEFAULT_EXCHANGE_FORMAT, DEFAULT_WORKBOOK_PATH, type DiffDeps, type DiffInput, type DiffSummary, type DuplicateKeyReport, EXCHANGE_FORMATS, type EditEntryDeps, type EditEntryInput, type EditEntryResult, type ExchangeFormat, type ExportWorkbookDeps, type ExportWorkbookInput, type ExportWorkbookResult, type GlossaryProvenance, type ImportWorkbookDeps, type ImportWorkbookInput, type IntegrityGateReason, type KeyIntegrityDeps, type KeyIntegrityEntry, type KeyIntegrityInput, type KeyValueDeps, type KeyValueInput, type KeyValueResult, LOCK_FILE_NAME, type LoadConfigOptions, type LoadLockFileDeps, type LoadLockFileInput, type LoadedConfig, type LocaleCheckSummary, type LocaleDiff, type LocaleFileSnapshot, type LocaleFinishedEvent, type LocaleKeyIntegrity, type LocaleNotice, type LocalePathResolver, type LocalePathResolverConfig, type LocaleSnapshotDelta, type LocaleStartedEvent, type LocaleStyle, type LocaleSummary, type LockFile, type LockHolder, type LockLocaleState, type LockStateDeps, type LockStateInput, type LockStateResult, type LockWaitEvent, type LockWaitListener, type MalformedRowReport, type NeedsReviewEntry, type ProgressEvent, type ProgressListener, type ProviderConfig, type ProviderId, type ReadLocaleFileSnapshotDeps, type ReadLocaleFileSnapshotInput, type RetranslateEntryDeps, type RetranslateEntryInput, type RetranslateEntryResult, type ReviewReasonCode, type RunBudget, type RunFinishedEvent, type RunStatusDeps, type RunStatusFile, type RunStatusInput, type RunStatusLocale, type RunStatusResult, type RunSummary, type RunTranslate, type ScaffoldableProviderId, SdkError, type SdkErrorCode, type SdkFs, type SdkNotice, type SdkNoticeCode, type SubBatchProgressEvent, type SupportedFormat$1 as SupportedFormat, type TranslateDeps, type TranslateInput, type TranslationMemory, type UsageSummary, type VerbatraConfig, type VerbatraConfigInput, type WatchController, type WatchDeps, type WatchInput, type WatchRunResult, type Watcher, check, createLocalePathResolver, defineConfig, diff, diffLocaleSnapshots, editEntry, exportWorkbook, importWorkbook, keyIntegrity, keyValue, loadConfig, loadConfigWithMeta, loadLockFile, lockState, readLocaleFileSnapshot, retranslateEntry, runStatus, scaffoldingMetadata, translate, verbatraConfigSchema, watch };
+export { type BudgetBehavior, CACHE_FILE_NAME, type CheckDeps, type CheckInput, type CheckSummary, type ConfigSource, type CreateProvider, type CreateWatcher, DEFAULT_DELIMITED_PATH, DEFAULT_EXCHANGE_FORMAT, DEFAULT_WORKBOOK_PATH, type DiffDeps, type DiffInput, type DiffSummary, type DoctorCheck, type DoctorCheckId, type DoctorCheckStatus, type DoctorDeps, type DoctorInput, type DoctorResult, type DuplicateKeyReport, EXCHANGE_FORMATS, type EditEntryDeps, type EditEntryInput, type EditEntryResult, type ExchangeFormat, type ExportWorkbookDeps, type ExportWorkbookInput, type ExportWorkbookResult, type GlossaryFileDeps, type GlossaryFileInput, type GlossaryProvenance, type ImportWorkbookDeps, type ImportWorkbookInput, type IntegrityGateReason, type KeyIntegrityDeps, type KeyIntegrityEntry, type KeyIntegrityInput, type KeyValueDeps, type KeyValueInput, type KeyValueResult, LOCK_FILE_NAME, type LoadConfigOptions, type LoadLockFileDeps, type LoadLockFileInput, type LoadedConfig, type LocaleCheckSummary, type LocaleDiff, type LocaleFileSnapshot, type LocaleFinishedEvent, type LocaleKeyIntegrity, type LocaleNotice, type LocalePathResolver, type LocalePathResolverConfig, type LocaleSnapshotDelta, type LocaleStartedEvent, type LocaleStyle, type LocaleSummary, type LockFile, type LockHolder, type LockLocaleState, type LockStateDeps, type LockStateInput, type LockStateResult, type LockWaitEvent, type LockWaitListener, type MalformedRowReport, type NeedsReviewEntry, type ProgressEvent, type ProgressListener, type ProviderConfig, type ProviderId, type ReadLocaleFileSnapshotDeps, type ReadLocaleFileSnapshotInput, type RetranslateEntryDeps, type RetranslateEntryInput, type RetranslateEntryResult, type ReviewReasonCode, type RunBudget, type RunFinishedEvent, type RunStatusDeps, type RunStatusFile, type RunStatusInput, type RunStatusLocale, type RunStatusResult, type RunSummary, type RunTranslate, type ScaffoldableProviderId, SdkError, type SdkErrorCode, type SdkFs, type SdkNotice, type SdkNoticeCode, type SubBatchProgressEvent, type SupportedFormat$1 as SupportedFormat, type TranslateDeps, type TranslateInput, type TranslationMemory, type UpdateGlossaryTermInput, type UsageSummary, type VerbatraConfig, type VerbatraConfigInput, type WatchController, type WatchDeps, type WatchInput, type WatchRunResult, type Watcher, check, createLocalePathResolver, defineConfig, diff, diffLocaleSnapshots, doctor, editEntry, exportWorkbook, importWorkbook, keyIntegrity, keyValue, loadConfig, loadConfigWithMeta, loadLockFile, lockState, readGlossaryFile, readLocaleFileSnapshot, retranslateEntry, runStatus, scaffoldingMetadata, translate, updateGlossaryTerm, verbatraConfigSchema, watch };