@verbatra/sdk 0.6.3 → 0.7.0

package/dist/index.d.cts

@@ -152,7 +152,10 @@ interface TranslateResult {
 /**
  * The single contract every provider implements. It is narrow enough that a machine-translation API like
  * DeepL fits it directly, while LLM providers implement it by delegating to {@link runLlmTranslation}.
- * A new provider attaches by implementing this and registering it in a {@link ProviderRegistry}.
+ * A new provider attaches by implementing this, then adding an entry to the `providerFactories` table
+ * in `packages/sdk/src/config/provider-config.ts` alongside its member of the `providerConfigSchema`
+ * union. That table is a mapped type over the union's id set, so a provider present in one but not the
+ * other fails to compile.
  *
  * Implementer invariants:
  * - Translatable strings are UNTRUSTED. They travel only as data to the provider; never splice them into
@@ -283,6 +286,14 @@ interface SdkFs {
     createExclusive(path: string, data: string): Promise<boolean>;
     /** Delete a file if present; a no-op if it is already absent. */
     deleteFile(path: string): Promise<void>;
+    /**
+     * Create a directory and every missing parent (mkdir -p); a no-op if it already exists.
+     *
+     * Optional so an `SdkFs` written against an earlier version stays valid, and because an in-memory
+     * test double has no directories to create. Only the delimited export calls it, right before writing
+     * one interchange file per locale into the directory the caller named.
+     */
+    mkdir?(path: string): Promise<void>;
 }
 
 /**
@@ -374,6 +385,11 @@ declare const verbatraConfigSchema: z.ZodObject<{
     }>;
     files: z.ZodObject<{
         pattern: z.ZodString;
+        localeStyle: z.ZodOptional<z.ZodEnum<{
+            literal: "literal";
+            posix: "posix";
+            android: "android";
+        }>>;
     }, z.core.$strict>;
     provider: z.ZodDiscriminatedUnion<[z.ZodObject<{
         id: z.ZodLiteral<"anthropic">;
@@ -527,6 +543,7 @@ type GlossaryProvenance = {
     readonly path: string;
 };
 
+/** Where {@link loadConfig} should obtain the configuration. The three sources are alternatives. */
 interface LoadConfigOptions {
     /** Directory to start the search from. Defaults to the current working directory. */
     readonly cwd?: string;
@@ -643,6 +660,15 @@ declare function loadConfig(options?: LoadConfigOptions): Promise<VerbatraConfig
  *   its timeout elapsed, because another process is holding it (or an orphaned lock file was left
  *   behind by a killed process); the message names the lock file's path (thrown by `translate`,
  *   `importWorkbook`, `editEntry`, and `retranslateEntry`).
+ * - `LOCALE_LAYOUT_INVALID`: the configured `files.pattern` and `files.localeStyle` cannot be
+ *   combined (a segment style needs the `{locale}` token to stand alone between separators), or the
+ *   declared style has no valid path spelling for a configured locale (`zh-Hans` under `posix`, for
+ *   instance), or a locale expands to something that is not a single path segment. Thrown by
+ *   `createLocalePathResolver`, and so by every entry point that resolves a locale to a path, before
+ *   any file is read and before any provider call.
+ * - `LOCALE_PATH_COLLISION`: two configured locales resolve to the same absolute file path, which
+ *   would make the path-to-locale direction meaningless and would let two concurrent locale workers
+ *   race on one file (thrown by `createLocalePathResolver`, at the same point as the above).
  * - `CONCURRENCY_INVALID`: the `concurrency` input is not an integer of at least 1 (thrown by
  *   `translate` and, per run, by `watch`, before any locale runs).
  * - `CONCURRENCY_BUDGET_CONFLICT`: a live run requested `concurrency` greater than 1 while a token
@@ -654,7 +680,7 @@ declare function loadConfig(options?: LoadConfigOptions): Promise<VerbatraConfig
  *   per-locale failure carries no string code of its own. See the surfaced-not-thrown distinction
  *   on `translate`.
  */
-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" | "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" | "LOCALE_LAYOUT_INVALID" | "LOCALE_PATH_COLLISION" | "CONCURRENCY_INVALID" | "CONCURRENCY_BUDGET_CONFLICT" | "LOCALE_FAILED";
 /** The single structured error the SDK throws or records. Never carries a secret. */
 declare class SdkError extends Error {
     /** The stable {@link SdkErrorCode} for this failure; branch on this, not the message. */
@@ -1395,12 +1421,19 @@ interface NeedsReviewEntry {
     readonly reasons: readonly ReviewReasonCode[];
 }
 /**
- * One row a workbook import could not read: the 1-based worksheet row number and the header label of
- * the offending column. Carries no cell content, so untrusted workbook text never reaches the summary.
+ * One row a workbook import could not read: the 1-based row number, the file line for a delimited
+ * import, and the header label of the offending column. Carries no cell content, so untrusted workbook
+ * text never reaches the summary.
  */
 interface MalformedRowReport {
     /** The 1-based worksheet row number of the malformed row. */
     readonly row: number;
+    /**
+     * The 1-based file line the malformed record starts on. Present only for a delimited (csv or tsv)
+     * import; an xlsx workbook has rows rather than lines. See {@link DuplicateKeyReport.line} for why
+     * both numbers are reported.
+     */
+    readonly line?: number;
     /** The header label of the column the row was rejected on (for example "Status"). */
     readonly column: string;
 }
@@ -1413,6 +1446,15 @@ interface DuplicateKeyReport {
     readonly key: string;
     /** The 1-based worksheet row number of the later occurrence that lost to the first. */
     readonly row: number;
+    /**
+     * The 1-based file line this later occurrence starts on. Present only for a delimited (csv or tsv)
+     * import.
+     *
+     * A delimited record holding a quoted line break covers one spreadsheet row but several editor
+     * lines, so `row` is the number a translator sees in a spreadsheet and `line` the one they see in a
+     * text editor. Both are reported so the position holds whichever tool they opened the file in.
+     */
+    readonly line?: number;
 }
 /** Structured outcome for one target locale; surfaced as data on the run, never thrown. */
 interface LocaleSummary {
@@ -1891,20 +1933,44 @@ interface TranslateDeps {
  */
 declare function translate(input: TranslateInput, deps?: TranslateDeps): Promise<RunSummary>;
 
+/**
+ * The two delimiter-separated interchange formats. They are one implementation with one parameter, the
+ * field delimiter: `tsv` is not a second format, it is `csv` with a tab.
+ */
+type DelimitedFormat = "csv" | "tsv";
+
+/**
+ * The interchange format a handoff moves in. `xlsx` is the default and the only shape that carries
+ * every target locale in one artifact; `csv` and `tsv` are plain text and move one file per target
+ * locale, so their path names a directory rather than a file.
+ */
+type ExchangeFormat = "xlsx" | DelimitedFormat;
+
 /** Default workbook output path, relative to the resolved working directory. */
 declare const DEFAULT_WORKBOOK_PATH = "verbatra-translations.xlsx";
+/**
+ * Default delimited output directory, relative to the resolved working directory. A delimited export
+ * writes one file per target locale, so its output path names a directory, not a file.
+ */
+declare const DEFAULT_DELIMITED_PATH = "verbatra-translations";
 /** Input for {@link exportWorkbook}: the validated config and where/how to run the export. */
 interface ExportWorkbookInput {
     /** The validated configuration (typically from {@link loadConfig}). */
     readonly config: VerbatraConfig;
     /** Directory the file pattern, lock-file, and output path resolve against; defaults to cwd. */
     readonly cwd?: string;
-    /** Output path for the workbook; defaults to {@link DEFAULT_WORKBOOK_PATH} under cwd. */
+    /**
+     * Output path; defaults to {@link DEFAULT_WORKBOOK_PATH} for `xlsx` and to
+     * {@link DEFAULT_DELIMITED_PATH} for `csv` and `tsv`. It is the workbook file for `xlsx` and the
+     * directory the per-locale files are written into for `csv` and `tsv` (created if missing).
+     */
     readonly out?: string;
     /** Subset of target locales to export; defaults to all configured target locales. */
     readonly locales?: readonly string[];
     /** Include unchanged keys (off by default; export is missing-and-changed only). */
     readonly includeUnchanged?: boolean;
+    /** Interchange format to write; defaults to `xlsx`, so an existing caller is unaffected. */
+    readonly format?: ExchangeFormat;
 }
 /** Composition seam for {@link exportWorkbook}: inject a registry and a file system for tests. */
 interface ExportWorkbookDeps {
@@ -1913,7 +1979,10 @@ interface ExportWorkbookDeps {
 }
 /** The outcome of an export: where it was written and how many rows per locale. */
 interface ExportWorkbookResult {
-    /** The absolute path the workbook was written to. */
+    /**
+     * The absolute path written to: the workbook file for `xlsx`, the directory holding one
+     * `<locale>.csv` or `<locale>.tsv` per exported locale for the delimited formats.
+     */
     readonly path: string;
     /** Per-locale row counts, in config order; the same set the workbook carries. */
     readonly locales: readonly {
@@ -1922,14 +1991,24 @@ interface ExportWorkbookResult {
     }[];
 }
 /**
- * Export the strings needing human translation into a styled `.xlsx` workbook. Each target locale is
- * diffed against the source and lock baseline to pick the rows (missing and changed by default; add
- * unchanged with `includeUnchanged`), and the bytes are written to `out`. No provider is called and no
- * lock-file is written.
+ * Export the strings needing human translation into a styled `.xlsx` workbook, or into one plain
+ * `.csv` or `.tsv` file per target locale. Each target locale is diffed against the source and lock
+ * baseline to pick the rows (missing and changed by default; add unchanged with `includeUnchanged`),
+ * and the result is written to `out`. No provider is called and no lock-file is written.
+ *
+ * The delimited formats trade the workbook's protection for a diffable, git-friendly handoff: a
+ * workbook leaves only the Translation column editable and hides the source hash, while every field of
+ * a delimited file is editable and its source hash is visible. An edited source hash is never trusted
+ * on import; it is compared against the live source and the row is withheld as drift.
+ *
+ * A delimited export also writes a small hidden manifest naming the locales it wrote. It exists so a
+ * re-export with a narrower `locales` selection retires the locales it dropped: their files stay on
+ * disk, but the next import recognizes them as leftovers from the earlier run and refuses to apply
+ * them. The export deletes nothing, so an unrelated file in the output directory is never at risk.
  *
  * @param input - The validated config and export options.
  * @param deps - Optional composition seams (registry, file system) for tests.
- * @returns Where the workbook was written and the per-locale row counts.
+ * @returns Where the export was written and the per-locale row counts.
  * @throws {@link SdkError} `UNKNOWN_FORMAT`, `SOURCE_UNREADABLE`, `SOURCE_INVALID`, `LOCK_FILE_INVALID`
  *   with the same meanings as in `translate`, or `UNKNOWN_LOCALE` when a requested locale is not
  *   among the configured target locales.
@@ -1940,12 +2019,17 @@ declare function exportWorkbook(input: ExportWorkbookInput, deps?: ExportWorkboo
 interface ImportWorkbookInput {
     /** The validated configuration (typically from {@link loadConfig}). */
     readonly config: VerbatraConfig;
-    /** Path to the filled workbook to import. */
+    /**
+     * Path to the filled handoff to import: the workbook file for `xlsx`, and for `csv` and `tsv`
+     * either one `<locale>.csv` / `<locale>.tsv` file or a directory holding one per target locale.
+     */
     readonly workbook: string;
     /** Directory the file pattern, lock-file, and workbook path resolve against; defaults to cwd. */
     readonly cwd?: string;
     /** When true, validate and report only: write no locale file and update no lock-file. */
     readonly dryRun?: boolean;
+    /** Interchange format to read; defaults to `xlsx`, so an existing caller is unaffected. */
+    readonly format?: ExchangeFormat;
 }
 /** Composition seam for {@link importWorkbook}: inject a registry and a file system for tests. */
 interface ImportWorkbookDeps {
@@ -1953,7 +2037,7 @@ interface ImportWorkbookDeps {
     readonly fs?: SdkFs;
 }
 /**
- * Import a filled workbook back into the locale files. Each target-locale data sheet runs the same
+ * Import a filled handoff back into the locale files. Each target-locale data sheet runs the same
  * source-drift, placeholder, and ICU checks as the translate flow, the accepted values are written
  * through the format adapter, and the lock is updated. Returns a {@link RunSummary} structurally
  * identical to `translate`'s.
@@ -1964,8 +2048,10 @@ interface ImportWorkbookDeps {
  * throw; per-row rejections are withheld and reported on the locale. A configured target locale with
  * no sheet at all (a deleted, renamed, or reordered tab) is reconciled after the sheet loop and
  * reported as that locale's `status: "failed"` (`WORKBOOK_SHEET_MISSING`) rather than silently
- * dropped. Dry-run validates and reports without writing any locale or lock file, and skips lock
- * acquisition (there is nothing to protect).
+ * dropped. For a delimited directory, a locale file the most recent export into that directory did not
+ * write is a leftover from an earlier, wider selection: it is never applied and is reported as that
+ * locale's `status: "failed"` (`HANDOFF_FILE_STALE`). Dry-run validates and reports without writing any
+ * locale or lock file, and skips lock acquisition (there is nothing to protect).
  *
  * The lock-file is read once, up front, for every sheet's diff baseline. On a non-dry-run, each
  * sheet's write-and-lock-update step then holds that locale's `withLocaleWriteLock` for its whole
@@ -1978,6 +2064,82 @@ interface ImportWorkbookDeps {
  */
 declare function importWorkbook(input: ImportWorkbookInput, deps?: ImportWorkbookDeps): Promise<RunSummary>;
 
+/** The locale styles a files pattern's `{locale}` token can expand under. */
+declare const LOCALE_STYLES: readonly ["literal", "posix", "android"];
+/**
+ * How a configured locale is spelled inside a path:
+ *
+ * - `literal` (the default) expands the token to the configured tag verbatim. This covers the
+ *   i18next, vue-i18n, next-intl, ngx-translate, XLIFF, YAML, and ARB layouts, and Apple's
+ *   `.lproj` naming, which is the BCP-47 tag as written.
+ * - `posix` replaces `-` with `_`, for gettext directories (`pt_BR/LC_MESSAGES/`) and the Java
+ *   `messages_{locale}.properties` suffix layout.
+ * - `android` expands the token to a complete Android resource-directory segment, `values` prefix
+ *   included, and is the only style that spells the source locale differently from a target.
+ *
+ * A style may be relaxed to accept a locale it previously refused, but the spelling it already
+ * produces must never change: a re-spelling orphans every file written under the old name, leaving
+ * a stale directory the platform still prefers.
+ */
+type LocaleStyle = (typeof LOCALE_STYLES)[number];
+
+/**
+ * The part of the project config locale-to-path resolution depends on. Deliberately structural, so a
+ * caller holding a full `VerbatraConfig` passes it unchanged while a test can build one inline.
+ */
+interface LocalePathResolverConfig {
+    readonly sourceLocale: string;
+    readonly targetLocales: readonly string[];
+    readonly files: {
+        readonly pattern: string;
+        readonly localeStyle?: LocaleStyle | undefined;
+    };
+}
+/**
+ * The project's locale-to-path mapping, resolved once from the config and threaded through every
+ * flow that needs a path. Holding one object rather than a `(pattern, style, sourceLocale)` triple
+ * is what keeps a source-aware style from producing a wrong path in a flow that only threaded part
+ * of it.
+ */
+interface LocalePathResolver {
+    /**
+     * The absolute file path for one locale. Never throws for a configured locale: every one of them
+     * is spelled and checked when the resolver is created.
+     *
+     * @throws SdkError `LOCALE_LAYOUT_INVALID` when the style cannot spell an unconfigured locale
+     * passed in after construction.
+     */
+    pathFor(locale: string): string;
+    /**
+     * Which configured locale a path belongs to, or `undefined` when it belongs to none of them. This
+     * is a lookup in the forward map, never a parse: the configured locale list is the only authority
+     * on which locales exist. A relative argument is resolved against the same `cwd` the resolver was
+     * created with; the match is exact, so a path differing only in case does not resolve even on a
+     * case-insensitive file system.
+     *
+     * `undefined` is not an error. It means the path is not one of this project's locale files, which
+     * is what a watcher needs to know in order to ignore it.
+     */
+    localeFor(absolutePath: string): string | undefined;
+}
+/**
+ * Creates the project's locale-to-path resolver. Every check runs here, before any file is read and
+ * before any provider call: the pattern must carry the `{locale}` token and must be combinable with
+ * the declared style, the style must have a valid spelling for the source locale and every target,
+ * and no two locales may resolve to the same path.
+ *
+ * Under the default `literal` style the produced path is the pattern with `{locale}` replaced by the
+ * configured tag, resolved against `cwd`, which is what every project without a `files.localeStyle`
+ * gets and is unchanged from before styles existed.
+ *
+ * @param cwd - Directory the files pattern resolves against.
+ * @param config - The project's locales, files pattern, and locale style.
+ * @throws SdkError `LOCALE_LAYOUT_INVALID` when the pattern and style cannot be combined, or the
+ * style cannot spell a configured locale.
+ * @throws SdkError `LOCALE_PATH_COLLISION` when two configured locales resolve to the same path.
+ */
+declare function createLocalePathResolver(cwd: string, config: LocalePathResolverConfig): LocalePathResolver;
+
 /**
  * The lock-file shape: for each target locale, a map of key to the source content hash from which that
  * target key was last translated. The baseline core's diff consumes to detect changed source strings.
@@ -2178,4 +2340,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_WORKBOOK_PATH, type DiffDeps, type DiffInput, type DiffSummary, type DuplicateKeyReport, type EditEntryDeps, type EditEntryInput, type EditEntryResult, 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 LocaleSnapshotDelta, type LocaleStartedEvent, 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, 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_WORKBOOK_PATH, type DiffDeps, type DiffInput, type DiffSummary, type DuplicateKeyReport, 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 };