@verbatra/sdk 0.9.1 → 0.10.0

package/dist/index.d.ts

@@ -1,6 +1,5 @@
 import { z } from 'zod';
 import Anthropic from '@anthropic-ai/sdk';
-import { Interactions } from '@google/genai';
 import OpenAI from 'openai';
 
 /**
@@ -236,12 +235,22 @@ interface TranslationProvider {
 type AnthropicModel = Anthropic.Messages.Model;
 
 /**
- * The Gemini authoring model type, sourced from the installed SDK's own model union so
- * verbatra restates no model IDs. It is an open union, so unknown model IDs are still
- * accepted. Type-only: it informs editor completions and is never validated at runtime,
- * where the schema stays `z.string().min(1)`.
- */
-type GeminiModel = Interactions.Model;
+ * The Gemini authoring model type. Unlike the sibling Anthropic and OpenAI model types, this
+ * union is hand-maintained rather than re-exported from `@google/genai`: every entry point of
+ * that package's `.d.ts` carries an unconditional top-level import of
+ * `@modelcontextprotocol/sdk/client/index.js`, an optional peer dependency it does not install.
+ * Re-exporting any type from that package, including its model union, drags that import into
+ * this package's own published types and breaks `tsc --noEmit` with `skipLibCheck: false` for
+ * any consumer who has not separately installed the MCP SDK. Keeping this list literal avoids
+ * that transitive dependency entirely.
+ *
+ * It is an open union (`(string & {})` at the end), so unknown or newly released model IDs are
+ * still accepted. Type-only: it informs editor completions and is never validated at runtime,
+ * where the schema stays `z.string().min(1)`. The list is current as of `@google/genai` 2.17.1
+ * and does not update automatically; refresh it by hand when adopting a newer SDK version that
+ * adds models worth completing on.
+ */
+type GeminiModel = "gemini-2.5-flash" | "gemini-2.5-pro" | "gemma-4-26b-a4b-it" | "gemma-4-31b-it" | "gemini-flash-latest" | "gemini-flash-lite-latest" | "gemini-pro-latest" | "gemini-2.5-flash-lite" | "gemini-2.5-flash-image" | "gemini-3-flash-preview" | "gemini-3.1-pro-preview" | "gemini-3.1-pro-preview-customtools" | "gemini-3.1-flash-lite" | "gemini-3-pro-image" | "nano-banana-pro-preview" | "gemini-3.1-flash-image" | "gemini-3.5-flash" | "gemini-3.6-flash" | "gemini-3.7-flash" | "lyria-3-clip-preview" | "lyria-3-pro-preview" | "gemini-robotics-er-1.6-preview" | "gemini-robotics-er-2-preview" | (string & {});
 
 /**
  * The OpenAI authoring model type, sourced from the OpenAI SDK's published chat-model union
@@ -251,13 +260,18 @@ type GeminiModel = Interactions.Model;
 type OpenAiModel = OpenAI.ChatModel;
 
 /**
- * Zod schema accepting exactly one of the eight source formats verbatra can read and write. Each
+ * Zod schema accepting exactly one of the twelve source formats verbatra can read and write. Each
  * member names the ecosystem it round-trips, not just a file extension, because several of them share
  * one: `i18next-json` is i18next's nested JSON with its plural key suffixes, `vue-i18n-json` is Vue
  * I18n's JSON with its pipe-separated plural values, `next-intl-json` is next-intl's ICU-message JSON,
- * and `ngx-translate-json` is ngx-translate's nested JSON. The remaining four are `xliff` (the XLIFF
- * interchange XML), `yaml` (plain nested YAML), `arb` (Flutter's Application Resource Bundle), and
- * `properties` (Java and Spring `.properties` files).
+ * and `ngx-translate-json` is ngx-translate's nested JSON. The remaining eight are `xliff` (the XLIFF
+ * interchange XML), `yaml` (plain nested YAML), `arb` (Flutter's Application Resource Bundle),
+ * `properties` (Java and Spring `.properties` files), `apple-strings` (Apple's flat `.strings`
+ * localization format for iOS and macOS), `apple-xcstrings` (Apple's Xcode String Catalog, a single
+ * JSON document holding every locale of a `.xcstrings` catalogue together), `android-xml` (Android's
+ * `res/values/strings.xml` resource format, including `<plurals>` and `translatable="false"` entries),
+ * and `gettext-po` (GNU gettext's `.po` and `.pot` catalogs, including `msgctxt` disambiguation and
+ * `msgid_plural`/`msgstr[n]` plural forms keyed by the file's own `Plural-Forms` index count).
  *
  * The set is closed: a format outside it cannot be represented, so adding one means adding a member
  * here and an adapter that claims it.
@@ -271,8 +285,12 @@ declare const supportedFormatSchema$1: z.ZodEnum<{
     yaml: "yaml";
     arb: "arb";
     properties: "properties";
+    "apple-strings": "apple-strings";
+    "apple-xcstrings": "apple-xcstrings";
+    "android-xml": "android-xml";
+    "gettext-po": "gettext-po";
 }>;
-/** One of the eight supported source formats; the inferred type of {@link supportedFormatSchema}. */
+/** One of the twelve supported source formats; the inferred type of {@link supportedFormatSchema}. */
 type SupportedFormat$1 = z.infer<typeof supportedFormatSchema$1>;
 
 /**
@@ -404,6 +422,11 @@ declare const providerConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         glossaryId: z.ZodOptional<z.ZodString>;
         requestTimeoutMs: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodLiteral<"google-translate">;
+    options: z.ZodObject<{
+        requestTimeoutMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
 }, z.core.$strip>, z.ZodObject<{
     id: z.ZodLiteral<"openai-compatible">;
     options: z.ZodObject<{
@@ -419,15 +442,16 @@ declare const providerConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
  * carries exactly the options it supports and nothing else.
  *
  * No variant has a field for an API key. Keys are read from the environment by the provider itself
- * (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `DEEPL_API_KEY`), which is what keeps
- * them out of config files and out of version control. The `openai-compatible` variant may name a
- * different environment variable through `apiKeyEnvVar`, but still never holds the key itself.
+ * (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `DEEPL_API_KEY`, or
+ * `GOOGLE_TRANSLATE_API_KEY`), which is what keeps them out of config files and out of version
+ * control. The `openai-compatible` variant may name a different environment variable through
+ * `apiKeyEnvVar`, but still never holds the key itself.
  */
 type ProviderConfig = z.infer<typeof providerConfigSchema>;
 /**
- * The identifier of a supported translation provider: `anthropic`, `openai`, `gemini`, `deepl`, or
- * `openai-compatible`. The last one targets a local or self-hosted server that speaks the OpenAI
- * chat-completions API.
+ * The identifier of a supported translation provider: `anthropic`, `openai`, `gemini`, `deepl`,
+ * `google-translate`, or `openai-compatible`. The last one targets a local or self-hosted server
+ * that speaks the OpenAI chat-completions API.
  */
 type ProviderId = ProviderConfig["id"];
 
@@ -460,6 +484,10 @@ declare const verbatraConfigSchema: z.ZodObject<{
         yaml: "yaml";
         arb: "arb";
         properties: "properties";
+        "apple-strings": "apple-strings";
+        "apple-xcstrings": "apple-xcstrings";
+        "android-xml": "android-xml";
+        "gettext-po": "gettext-po";
     }>;
     files: z.ZodObject<{
         pattern: z.ZodString;
@@ -496,6 +524,11 @@ declare const verbatraConfigSchema: z.ZodObject<{
             glossaryId: z.ZodOptional<z.ZodString>;
             requestTimeoutMs: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strict>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodLiteral<"google-translate">;
+        options: z.ZodObject<{
+            requestTimeoutMs: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>;
     }, z.core.$strip>, z.ZodObject<{
         id: z.ZodLiteral<"openai-compatible">;
         options: z.ZodObject<{
@@ -569,9 +602,9 @@ type AuthoringVariant<Id extends ProviderId, M extends string> = Extract<Provide
 } : never : never;
 /**
  * Maps each provider ID to its authoring-time config variant. The three language-model providers
- * get narrowed model unions; DeepL has no model to narrow, and `openai-compatible` deliberately
- * keeps a free-form model string because the endpoint is a local or self-hosted server whose model
- * list the SDK cannot know ahead of time.
+ * get narrowed model unions; DeepL and Google Cloud Translation have no model to narrow, and
+ * `openai-compatible` deliberately keeps a free-form model string because the endpoint is a local
+ * or self-hosted server whose model list the SDK cannot know ahead of time.
  */
 type AuthoringProviderVariant = {
     /** Anthropic, with `model` narrowed to the Claude model IDs. */
@@ -584,6 +617,13 @@ type AuthoringProviderVariant = {
     deepl: Extract<ProviderConfig, {
         id: "deepl";
     }>;
+    /**
+     * Google Cloud Translation (Basic, v2), which takes no model for the same reason as DeepL: it is
+     * a machine-translation API rather than a language model.
+     */
+    "google-translate": Extract<ProviderConfig, {
+        id: "google-translate";
+    }>;
     /** A local or self-hosted OpenAI-compatible endpoint, whose model stays a free-form string. */
     "openai-compatible": Extract<ProviderConfig, {
         id: "openai-compatible";
@@ -662,6 +702,14 @@ declare function defineConfig(config: AuthoringConfigFor<"gemini">): VerbatraCon
  * @returns The same object, typed as {@link VerbatraConfigInput}.
  */
 declare function defineConfig(config: AuthoringConfigFor<"deepl">): VerbatraConfigInput;
+/**
+ * Types a `verbatra.config.ts` narrowed to the Google Cloud Translation provider. Like DeepL, it is
+ * a machine-translation API rather than a language model, so its options carry no model field.
+ *
+ * @param config - The config object, narrowed to the Google Cloud Translation provider.
+ * @returns The same object, typed as {@link VerbatraConfigInput}.
+ */
+declare function defineConfig(config: AuthoringConfigFor<"google-translate">): VerbatraConfigInput;
 /**
  * Types a `verbatra.config.ts` for any supported provider. This is the fallback overload, and the
  * one that serves `openai-compatible`, where the model is a free-form string because the endpoint
@@ -795,8 +843,8 @@ interface LoadConfigOptions {
  */
 type ConfigSource = {
     /**
-     * `search` means cosmiconfig found the file by walking up from the working directory;
-     * `explicit` means the caller named it through `configPath`.
+     * `search` means cosmiconfig found the file by walking up from the working directory, up to
+     * the nearest `.git` directory; `explicit` means the caller named it through `configPath`.
      */
     readonly kind: "search" | "explicit";
     /** The absolute path of the config file that was loaded. */
@@ -821,12 +869,26 @@ interface LoadedConfig {
  *
  * Resolution order is: an explicit `configOverride`, then an explicit `configPath`, then a
  * cosmiconfig search upward from `cwd` across `verbatra.config.ts`, the `.verbatrarc` family, and a
- * `verbatra` property in `package.json`. A `configPath` that does not exist is an error rather than
- * a fallback to searching, so a typo in a path never silently loads a different project's config.
+ * `verbatra` property in `package.json`. The upward search stops at the nearest ancestor directory
+ * containing a `.git` entry; if none is found, it stops at the user's home directory when that is an
+ * ancestor of `cwd`, and otherwise it does not search above `cwd` at all, so a nested workspace
+ * package finds a config at its monorepo root without wandering above it, and a project outside the
+ * home directory tree (a CI checkout, for instance) never triggers an unbounded walk to the
+ * filesystem root. A config file outside that directory chain, including cosmiconfig's own OS-level
+ * global config directory, is never used, even though the underlying search strategy checks it; it is
+ * treated the same as no config found. A `configPath` that does not exist is an error rather than a
+ * fallback to searching, so a typo in a path never silently loads a different project's config.
  *
  * A glossary given as a path is read and validated here, so the returned config always carries a
  * resolved term map.
  *
+ * A `verbatra.config.ts` file is transpiled and loaded through jiti. When it imports `@verbatra/sdk`
+ * or `@verbatra/cli`, those bare specifiers are aliased to the package that is actually running this
+ * function, so the import resolves to the running version even when a different, conflicting version
+ * of either package also happens to be reachable from the config file's own location. A package is
+ * only aliased when its own entry point can be resolved from the running code; otherwise the import
+ * falls back to jiti's ordinary bare-specifier resolution, unchanged from before this behavior existed.
+ *
  * @param options - Where and how to look for the config.
  * @returns The validated config with its config-source and glossary provenance.
  *
@@ -841,8 +903,10 @@ declare function loadConfigWithMeta(options?: LoadConfigOptions): Promise<Loaded
  * pass the result to {@link translate}, {@link check}, {@link diff}, or any other entry point.
  *
  * Resolution order is an explicit `configOverride`, then an explicit `configPath`, then a
- * cosmiconfig search upward from `cwd`. A glossary declared as a file path is read and validated
- * here, so the returned {@link VerbatraConfig} always carries a resolved term map.
+ * cosmiconfig search upward from `cwd`, stopping at the nearest ancestor `.git` directory, or
+ * failing that, the user's home directory when it is an ancestor of `cwd`, or failing that, `cwd`
+ * itself. A glossary declared as a file path is read and validated here, so the returned
+ * {@link VerbatraConfig} always carries a resolved term map.
  *
  * Reach for {@link loadConfigWithMeta} when you also need to know which file was loaded.
  *
@@ -963,13 +1027,18 @@ declare class SdkError extends Error {
 }
 
 /**
- * Zod schema accepting exactly one of the eight source formats verbatra can read and write. Each
+ * Zod schema accepting exactly one of the twelve source formats verbatra can read and write. Each
  * member names the ecosystem it round-trips, not just a file extension, because several of them share
  * one: `i18next-json` is i18next's nested JSON with its plural key suffixes, `vue-i18n-json` is Vue
  * I18n's JSON with its pipe-separated plural values, `next-intl-json` is next-intl's ICU-message JSON,
- * and `ngx-translate-json` is ngx-translate's nested JSON. The remaining four are `xliff` (the XLIFF
- * interchange XML), `yaml` (plain nested YAML), `arb` (Flutter's Application Resource Bundle), and
- * `properties` (Java and Spring `.properties` files).
+ * and `ngx-translate-json` is ngx-translate's nested JSON. The remaining eight are `xliff` (the XLIFF
+ * interchange XML), `yaml` (plain nested YAML), `arb` (Flutter's Application Resource Bundle),
+ * `properties` (Java and Spring `.properties` files), `apple-strings` (Apple's flat `.strings`
+ * localization format for iOS and macOS), `apple-xcstrings` (Apple's Xcode String Catalog, a single
+ * JSON document holding every locale of a `.xcstrings` catalogue together), `android-xml` (Android's
+ * `res/values/strings.xml` resource format, including `<plurals>` and `translatable="false"` entries),
+ * and `gettext-po` (GNU gettext's `.po` and `.pot` catalogs, including `msgctxt` disambiguation and
+ * `msgid_plural`/`msgstr[n]` plural forms keyed by the file's own `Plural-Forms` index count).
  *
  * The set is closed: a format outside it cannot be represented, so adding one means adding a member
  * here and an adapter that claims it.
@@ -983,8 +1052,12 @@ declare const supportedFormatSchema: z.ZodEnum<{
     yaml: "yaml";
     arb: "arb";
     properties: "properties";
+    "apple-strings": "apple-strings";
+    "apple-xcstrings": "apple-xcstrings";
+    "android-xml": "android-xml";
+    "gettext-po": "gettext-po";
 }>;
-/** One of the eight supported source formats; the inferred type of {@link supportedFormatSchema}. */
+/** One of the twelve supported source formats; the inferred type of {@link supportedFormatSchema}. */
 type SupportedFormat = z.infer<typeof supportedFormatSchema>;
 
 /**
@@ -1062,10 +1135,13 @@ interface ReadResult {
      */
     readonly invalidIcuKeys: readonly string[];
     /**
-     * Dotted paths of leaves that were present in the source but excluded because they are not
-     * strings (a stray number, boolean, or null). These are never translated, hashed, diffed, or
-     * checked for placeholder or ICU integrity, and are not written back if the file is later
-     * rewritten. Empty for a file with no such leaves.
+     * Keys or dotted paths that were present in the source but excluded from translation: a stray
+     * non-string leaf (a number, boolean, or null) for a tree-based format, or a key the format's own
+     * metadata marks as not translatable. These are never translated, hashed, diffed, or checked for
+     * placeholder or ICU integrity. Whether one survives a later rewrite of the same file depends on
+     * the adapter: an adapter that reconstructs the whole file from `resource.entries` alone drops it,
+     * while an adapter that patches only the entries it touches into the existing document (for
+     * example `apple-xcstrings`) preserves it verbatim. Empty for a file with no such leaves.
      */
     readonly excludedLeafPaths: readonly string[];
 }
@@ -1785,6 +1861,90 @@ interface LocaleSnapshotDelta {
  */
 declare function diffLocaleSnapshots(previous: LocaleFileSnapshot, current: LocaleFileSnapshot): LocaleSnapshotDelta;
 
+/** One key's current source and target text within a {@link LocaleValues} map. */
+interface KeyValuePair {
+    /** The key's text in the source locale, absent when the key exists only in this target (orphaned). */
+    readonly source?: string;
+    /** The key's text in this target locale, absent when the key has not been translated yet. */
+    readonly target?: string;
+}
+/** One target locale's current source and target text for every key, as returned by {@link localeValues}. */
+interface LocaleValues {
+    /** The target locale these values were read for. */
+    readonly locale: string;
+    /**
+     * Source and target text per key, keyed by key name. Covers missing, changed, orphaned, and
+     * in-sync keys alike.
+     */
+    readonly values: Readonly<Record<string, KeyValuePair>>;
+}
+/** Input for {@link localeValues}. */
+interface LocaleValuesInput {
+    /** The resolved project config, normally from {@link loadConfig}. */
+    readonly config: VerbatraConfig;
+    /** Directory the `files.pattern` is resolved against. Defaults to the process working directory. */
+    readonly cwd?: string;
+    /** Restrict the report to these target locales. Defaults to every configured target locale. */
+    readonly locales?: readonly string[];
+}
+/** Injectable dependencies for {@link localeValues}. Every field has a working default. */
+interface LocaleValuesDeps {
+    /** Format-adapter registry to resolve the configured format. Defaults to the built-in registry. */
+    readonly adapterRegistry?: AdapterRegistry;
+    /** File-system port. Defaults to the real file system. */
+    readonly fs?: SdkFs;
+}
+/**
+ * Reads every key's current source and target text, across every requested target locale, in one
+ * pass over the files already on disk. It writes nothing and calls no provider.
+ *
+ * This exists to back client-side search over translation content rather than key names alone: a
+ * caller holding the result in memory can match a query against source or target text without a
+ * further round trip per key. {@link keyValue} and {@link diff} answer narrower questions (one key,
+ * or key names only); this is the bulk read a caller would otherwise have to simulate with many
+ * {@link keyValue} calls.
+ *
+ * A key present in the source but not yet translated in a locale reports `target` as absent; a key
+ * present in a locale but no longer in the source (orphaned) reports `source` as absent instead. A
+ * target locale file that does not exist yet is treated as empty rather than as an error, so every
+ * key in a newly added locale reports `target` as absent.
+ *
+ * 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.
+ * @returns Per-locale source and target text, keyed by key name.
+ *
+ * @throws {@link SdkError} `UNKNOWN_FORMAT`: no adapter is registered for the configured format.
+ * @throws {@link SdkError} `LOCALE_LAYOUT_INVALID`: the `files.pattern` and `files.localeStyle`
+ * 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} `SOURCE_UNREADABLE`: the source locale file does not exist.
+ * @throws {@link SdkError} `SOURCE_INVALID`: the source locale file could not be parsed.
+ * @throws {@link SdkError} `UNKNOWN_LOCALE`: a requested locale is not a configured target locale.
+ *
+ * @example
+ * ```ts
+ * import { loadConfig, localeValues } from "@verbatra/sdk";
+ *
+ * const config = await loadConfig();
+ * const locales = await localeValues({ config });
+ *
+ * const needle = "welcome";
+ * for (const locale of locales) {
+ *   for (const [key, pair] of Object.entries(locale.values)) {
+ *     if (pair.target?.toLowerCase().includes(needle)) {
+ *       console.log(`${locale.locale} ${key}: ${pair.target}`);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare function localeValues(input: LocaleValuesInput, deps?: LocaleValuesDeps): Promise<readonly LocaleValues[]>;
+
 /** One locale's lock-file baseline and the drift measured against it. */
 interface LockLocaleState {
     /** The target locale this entry describes. */
@@ -2593,9 +2753,10 @@ interface ExportWorkbookResult {
  * 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.
+ * resolves to a location the process lacks permission to write, or the device is full. A missing
+ * output directory is created automatically and is not a cause. Branch on the Node `code`, such as
+ * `EACCES` or `ENOSPC`, 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>;
 
@@ -2696,6 +2857,12 @@ interface LocalePathResolverConfig {
     readonly sourceLocale: string;
     /** Every target locale. All of them are mapped up front so collisions are caught immediately. */
     readonly targetLocales: readonly string[];
+    /**
+     * The configured format. Every format maps each locale to a distinct path except a
+     * shared-catalogue format (one holding every locale in a single file, such as `apple-xcstrings`),
+     * which maps every locale to the same path.
+     */
+    readonly format: SupportedFormat$1;
     /** The file layout. */
     readonly files: {
         /** The path pattern, which must contain the `{locale}` token. */
@@ -2715,6 +2882,9 @@ interface LocalePathResolver {
      * The configured locale owning an absolute path, or `undefined` when the path belongs to no
      * configured locale. The path is normalized before lookup, so a relative or non-canonical path
      * still resolves.
+     *
+     * Always `undefined` for a shared-catalogue format: every configured locale resolves to the same
+     * path there, so no single locale owns it.
      */
     localeFor(absolutePath: string): string | undefined;
 }
@@ -2730,15 +2900,21 @@ interface LocalePathResolver {
  * path collision is reported here, before any file is read and before any provider is called,
  * rather than partway through a run.
  *
+ * For a shared-catalogue format (such as `apple-xcstrings`), `pathFor` resolves every locale to the
+ * same path (the `{locale}` token is still required in the pattern but substitutes to the empty
+ * string), no locale style is applied, and `localeFor` always returns `undefined` rather than
+ * reporting a collision: every configured locale sharing one path is the expected shape for these
+ * formats, not a configuration mistake.
+ *
  * @param cwd - Directory the pattern is resolved against.
- * @param config - The source locale, target locales, and file layout.
+ * @param config - The source locale, target locales, format, and file layout.
  * @returns A resolver mapping locales to paths and paths back to locales.
  *
  * @throws {@link SdkError} `LOCALE_LAYOUT_INVALID`: the pattern lacks the `{locale}` token, a
  * segment style's token does not stand alone between separators, or a configured locale has no
  * valid single-segment spelling under the declared style.
  * @throws {@link SdkError} `LOCALE_PATH_COLLISION`: two configured locales resolve to the same
- * absolute path.
+ * absolute path, for a format that is not a shared-catalogue format.
  */
 declare function createLocalePathResolver(cwd: string, config: LocalePathResolverConfig): LocalePathResolver;
 
@@ -2793,6 +2969,33 @@ declare function loadLockFile(input?: LoadLockFileInput, deps?: LoadLockFileDeps
  */
 declare const LOCK_FILE_NAME = "verbatra.lock.json";
 
+/**
+ * Scrubs provider API key shapes and any currently configured provider environment variable value
+ * out of a string, replacing each match with `[REDACTED]`.
+ *
+ * Two independent passes run: a set of shape patterns for the major providers (OpenAI-style `sk-`
+ * keys, Gemini-style `AIza` keys, and hex UUID-shaped keys, with or without a `:fx` suffix), and an
+ * exact-value scrub of whatever `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`,
+ * `DEEPL_API_KEY`, `GOOGLE_TRANSLATE_API_KEY`, or `OPENAI_COMPATIBLE_API_KEY` currently holds in
+ * the process environment. Use this on any text a surface returns to a caller that did not itself
+ * generate that text, such as a file path, a config value, or an upstream error message, so a key
+ * value already present in the environment or written by a user can never reach an agent, a
+ * browser tab, or a log line.
+ *
+ * @param text - The text to scrub.
+ * @returns The same text with every matching key shape and configured key value replaced by
+ * `[REDACTED]`.
+ *
+ * @example
+ * ```ts
+ * import { redact } from "@verbatra/sdk";
+ *
+ * redact("key is sk-abcdEFGH12345678 in the log");
+ * // "key is [REDACTED] in the log"
+ * ```
+ */
+declare function redact(text: string): string;
+
 /**
  * A provider that project scaffolding can offer out of the box. It excludes `openai-compatible`,
  * which needs a `baseUrl` and a model name that only the user can supply, so there is nothing
@@ -2815,8 +3018,12 @@ declare const scaffoldingMetadata: {
         readonly openai: "OPENAI_API_KEY";
         readonly gemini: "GEMINI_API_KEY";
         readonly deepl: "DEEPL_API_KEY";
+        readonly "google-translate": "GOOGLE_TRANSLATE_API_KEY";
     };
-    /** A reasonable default model to prefill per language-model provider. DeepL has none, since it takes no model. */
+    /**
+     * A reasonable default model to prefill per language-model provider. DeepL and Google Cloud
+     * Translation have none, since neither takes a model.
+     */
     readonly scaffoldModels: {
         readonly anthropic: "claude-sonnet-4-6";
         readonly openai: "gpt-5.4-mini";
@@ -2827,7 +3034,7 @@ declare const scaffoldingMetadata: {
      * not agree: Anthropic calls it `maxTokens` and the others `maxOutputTokens`. A generator that
      * prefills a token limit must read the key from here rather than assume one, because
      * {@link verbatraConfigSchema} validates each provider's options strictly and rejects the wrong
-     * one. DeepL has no entry, since it takes no token limit.
+     * one. DeepL and Google Cloud Translation have no entry, since neither takes a token limit.
      */
     readonly providerTokenLimitKeys: {
         readonly anthropic: "maxTokens";
@@ -2835,7 +3042,7 @@ declare const scaffoldingMetadata: {
         readonly gemini: "maxOutputTokens";
     };
     /** Every i18n file format the SDK can read and write. */
-    readonly supportedFormats: readonly ["i18next-json", "vue-i18n-json", "next-intl-json", "ngx-translate-json", "xliff", "yaml", "arb", "properties"];
+    readonly supportedFormats: readonly ["i18next-json", "vue-i18n-json", "next-intl-json", "ngx-translate-json", "xliff", "yaml", "arb", "properties", "apple-strings", "apple-xcstrings", "android-xml", "gettext-po"];
 };
 
 /**
@@ -2980,4 +3187,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 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 };
+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 KeyValuePair, 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 LocaleValues, type LocaleValuesDeps, type LocaleValuesInput, 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, localeValues, lockState, readGlossaryFile, readLocaleFileSnapshot, redact, retranslateEntry, runStatus, scaffoldingMetadata, translate, updateGlossaryTerm, verbatraConfigSchema, watch };