@verbatra/sdk 0.5.0-next.3 → 0.5.0-next.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.cjs +470 -63
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +112 -15
- package/dist/index.d.ts +112 -15
- package/dist/index.js +467 -60
- package/dist/index.js.map +1 -1
- package/package.json +3 -3
package/dist/index.d.cts
CHANGED
|
@@ -3,19 +3,6 @@ import Anthropic from '@anthropic-ai/sdk';
|
|
|
3
3
|
import { Interactions } from '@google/genai';
|
|
4
4
|
import OpenAI from 'openai';
|
|
5
5
|
|
|
6
|
-
/** Zod schema accepting exactly one of {@link SUPPORTED_FORMATS}. */
|
|
7
|
-
declare const supportedFormatSchema$1: z.ZodEnum<{
|
|
8
|
-
"i18next-json": "i18next-json";
|
|
9
|
-
"vue-i18n-json": "vue-i18n-json";
|
|
10
|
-
"next-intl-json": "next-intl-json";
|
|
11
|
-
"ngx-translate-json": "ngx-translate-json";
|
|
12
|
-
xliff: "xliff";
|
|
13
|
-
yaml: "yaml";
|
|
14
|
-
arb: "arb";
|
|
15
|
-
}>;
|
|
16
|
-
/** One of the supported source formats; a member of {@link SUPPORTED_FORMATS}. */
|
|
17
|
-
type SupportedFormat$1 = z.infer<typeof supportedFormatSchema$1>;
|
|
18
|
-
|
|
19
6
|
/**
|
|
20
7
|
* A single, format-neutral translation unit. Placeholders are supplied already
|
|
21
8
|
* extracted; core never derives them from the value.
|
|
@@ -124,6 +111,24 @@ interface ProviderNotice {
|
|
|
124
111
|
/** A static, safe description; never a key or translatable content. */
|
|
125
112
|
readonly message: string;
|
|
126
113
|
}
|
|
114
|
+
/**
|
|
115
|
+
* Stable codes for a derived, per-key "needs review" signal. This is verbatra's own computed
|
|
116
|
+
* assessment, never a raw model self-score: four are recomputable from plain source/translated
|
|
117
|
+
* values (see the shared heuristic function), and `PROVIDER_DEGRADED` is applied by the caller from
|
|
118
|
+
* a provider notice.
|
|
119
|
+
*
|
|
120
|
+
* - `LENGTH_RATIO_OUTLIER`: the translated value's length is far shorter or longer than the source's.
|
|
121
|
+
* - `EQUALS_SOURCE`: the translated value equals the source value verbatim.
|
|
122
|
+
* - `GLOSSARY_TERM_MISSED`: a configured glossary target term did not appear in the translation.
|
|
123
|
+
* - `INTEGRITY_REORDERED`: the placeholder set matched but landed in a different order.
|
|
124
|
+
* - `PROVIDER_DEGRADED`: the batch this key came from carried a graceful-degradation notice.
|
|
125
|
+
*/
|
|
126
|
+
type ReviewReasonCode = "LENGTH_RATIO_OUTLIER" | "EQUALS_SOURCE" | "GLOSSARY_TERM_MISSED" | "INTEGRITY_REORDERED" | "PROVIDER_DEGRADED";
|
|
127
|
+
/** A key flagged for human review, carrying every reason code that applies. */
|
|
128
|
+
interface ReviewFlag {
|
|
129
|
+
readonly status: "review";
|
|
130
|
+
readonly reasons: readonly ReviewReasonCode[];
|
|
131
|
+
}
|
|
127
132
|
/** Result of a batch translation: per-key values, per-key integrity outcomes, and any notices. */
|
|
128
133
|
interface TranslateResult {
|
|
129
134
|
/** The translated value for each requested key. */
|
|
@@ -138,6 +143,11 @@ interface TranslateResult {
|
|
|
138
143
|
* report returns an empty array rather than omitting the field.
|
|
139
144
|
*/
|
|
140
145
|
readonly notices?: readonly ProviderNotice[];
|
|
146
|
+
/**
|
|
147
|
+
* Derived per-key review flags for this batch. A key absent from the map is implicitly "ok"; a
|
|
148
|
+
* present key carries one or more {@link ReviewReasonCode}s. Optional and additive.
|
|
149
|
+
*/
|
|
150
|
+
readonly reviewFlags?: ReadonlyMap<string, ReviewFlag>;
|
|
141
151
|
}
|
|
142
152
|
/**
|
|
143
153
|
* The single contract every provider implements. It is narrow enough that a machine-translation API like
|
|
@@ -212,6 +222,19 @@ type GeminiModel = Interactions.Model;
|
|
|
212
222
|
*/
|
|
213
223
|
type OpenAiModel = OpenAI.ChatModel;
|
|
214
224
|
|
|
225
|
+
/** Zod schema accepting exactly one of {@link SUPPORTED_FORMATS}. */
|
|
226
|
+
declare const supportedFormatSchema$1: z.ZodEnum<{
|
|
227
|
+
"i18next-json": "i18next-json";
|
|
228
|
+
"vue-i18n-json": "vue-i18n-json";
|
|
229
|
+
"next-intl-json": "next-intl-json";
|
|
230
|
+
"ngx-translate-json": "ngx-translate-json";
|
|
231
|
+
xliff: "xliff";
|
|
232
|
+
yaml: "yaml";
|
|
233
|
+
arb: "arb";
|
|
234
|
+
}>;
|
|
235
|
+
/** One of the supported source formats; a member of {@link SUPPORTED_FORMATS}. */
|
|
236
|
+
type SupportedFormat$1 = z.infer<typeof supportedFormatSchema$1>;
|
|
237
|
+
|
|
215
238
|
/**
|
|
216
239
|
* The provider section of the config: a discriminated union over the provider id, reusing each
|
|
217
240
|
* provider's own config schema. There is no key field anywhere in this union except
|
|
@@ -314,6 +337,11 @@ declare const verbatraConfigSchema: z.ZodObject<{
|
|
|
314
337
|
prune: z.ZodOptional<z.ZodBoolean>;
|
|
315
338
|
generatePlurals: z.ZodOptional<z.ZodBoolean>;
|
|
316
339
|
maxBatchSize: z.ZodOptional<z.ZodNumber>;
|
|
340
|
+
maxTokens: z.ZodOptional<z.ZodNumber>;
|
|
341
|
+
budgetBehavior: z.ZodOptional<z.ZodEnum<{
|
|
342
|
+
warn: "warn";
|
|
343
|
+
stop: "stop";
|
|
344
|
+
}>>;
|
|
317
345
|
}, z.core.$strict>;
|
|
318
346
|
/**
|
|
319
347
|
* The as-authored (or as-parsed) shape of the verbatra configuration, straight from the schema: `glossary`
|
|
@@ -623,6 +651,13 @@ interface ReadResult {
|
|
|
623
651
|
readonly resource: LocaleResource;
|
|
624
652
|
/** Keys whose values are invalid for the format's message syntax. Empty for non-ICU formats. */
|
|
625
653
|
readonly invalidIcuKeys: readonly string[];
|
|
654
|
+
/**
|
|
655
|
+
* Dotted paths of leaves that were present in the source but excluded because they are not
|
|
656
|
+
* strings (a stray number, boolean, or null). These are never translated, hashed, diffed, or
|
|
657
|
+
* checked for placeholder or ICU integrity, and are not written back if the file is later
|
|
658
|
+
* rewritten. Empty for a file with no such leaves.
|
|
659
|
+
*/
|
|
660
|
+
readonly excludedLeafPaths: readonly string[];
|
|
626
661
|
}
|
|
627
662
|
/**
|
|
628
663
|
* The contract every format adapter implements. A new format attaches by implementing this interface
|
|
@@ -907,7 +942,32 @@ interface LockStateDeps {
|
|
|
907
942
|
declare function lockState(input: LockStateInput, deps?: LockStateDeps): Promise<LockStateResult>;
|
|
908
943
|
|
|
909
944
|
/** A stable code for an SDK-originated notice (not a provider notice). */
|
|
910
|
-
type SdkNoticeCode = "PLURAL_CATEGORIES_INCOMPLETE" | "SUB_BATCH_FAILED" | "BLANK_ROW_BASELINE_RETAINED";
|
|
945
|
+
type SdkNoticeCode = "PLURAL_CATEGORIES_INCOMPLETE" | "SUB_BATCH_FAILED" | "BLANK_ROW_BASELINE_RETAINED" | "BUDGET_TOKENS_EXCEEDED";
|
|
946
|
+
/** Summed token usage across every provider call in a scope (one locale, or the whole run). */
|
|
947
|
+
interface UsageSummary {
|
|
948
|
+
readonly inputTokens: number;
|
|
949
|
+
readonly outputTokens: number;
|
|
950
|
+
}
|
|
951
|
+
/** The configured token-budget behavior: warn and continue, or stop making further provider calls. */
|
|
952
|
+
type BudgetBehavior = "warn" | "stop";
|
|
953
|
+
/**
|
|
954
|
+
* The run-wide token-budget outcome, present on {@link RunSummary} only when `maxTokens` is configured.
|
|
955
|
+
* `supported: false` means the configured provider never reported usage in this run (a token-less
|
|
956
|
+
* provider such as DeepL, or a dry-run): the guardrail is honestly inert, `tokensUsed` stays `0`, and
|
|
957
|
+
* `exceeded` stays `false`, never a false trip.
|
|
958
|
+
*/
|
|
959
|
+
interface RunBudget {
|
|
960
|
+
/** The configured ceiling. */
|
|
961
|
+
readonly maxTokens: number;
|
|
962
|
+
/** The configured behavior once the ceiling is reached. */
|
|
963
|
+
readonly behavior: BudgetBehavior;
|
|
964
|
+
/** Whether the configured provider reported usage at all this run. */
|
|
965
|
+
readonly supported: boolean;
|
|
966
|
+
/** Cumulative input plus output tokens across the run so far. */
|
|
967
|
+
readonly tokensUsed: number;
|
|
968
|
+
/** Whether `tokensUsed` reached or passed `maxTokens` at any point this run. */
|
|
969
|
+
readonly exceeded: boolean;
|
|
970
|
+
}
|
|
911
971
|
/**
|
|
912
972
|
* A notice raised by the SDK itself (not a provider), structurally identical to a {@link ProviderNotice}
|
|
913
973
|
* so both share the {@link LocaleSummary.notices} channel. Carries only a stable code and a static,
|
|
@@ -921,6 +981,13 @@ interface SdkNotice {
|
|
|
921
981
|
}
|
|
922
982
|
/** A notice on a locale summary: either a provider-emitted notice or an SDK-emitted one. */
|
|
923
983
|
type LocaleNotice = ProviderNotice | SdkNotice;
|
|
984
|
+
/** One key flagged for human review, and every reason code that applies to it. */
|
|
985
|
+
interface NeedsReviewEntry {
|
|
986
|
+
/** The flagged key. */
|
|
987
|
+
readonly key: string;
|
|
988
|
+
/** Every {@link ReviewReasonCode} that applies to this key. */
|
|
989
|
+
readonly reasons: readonly ReviewReasonCode[];
|
|
990
|
+
}
|
|
924
991
|
/** Structured outcome for one target locale; surfaced as data on the run, never thrown. */
|
|
925
992
|
interface LocaleSummary {
|
|
926
993
|
/** The target locale this summary is for. */
|
|
@@ -966,12 +1033,35 @@ interface LocaleSummary {
|
|
|
966
1033
|
* and acted, and empty in a dry-run.
|
|
967
1034
|
*/
|
|
968
1035
|
readonly generated: readonly string[];
|
|
1036
|
+
/**
|
|
1037
|
+
* Candidate keys never sent to the provider because a configured `maxTokens` budget already tripped
|
|
1038
|
+
* in `"stop"` mode: keys remaining in the current locale once the ceiling was crossed, and every
|
|
1039
|
+
* candidate key of a later, fully-skipped locale. Always present, empty by default, same convention as
|
|
1040
|
+
* {@link LocaleSummary.integrityMismatches} and {@link LocaleSummary.providerFailures}. Each key keeps
|
|
1041
|
+
* its prior lock hash and is picked up again next run, exactly like a `providerFailures` key.
|
|
1042
|
+
*/
|
|
1043
|
+
readonly budgetWithheld: readonly string[];
|
|
1044
|
+
/**
|
|
1045
|
+
* Summed token usage across every provider call for this locale (main translation plus plural
|
|
1046
|
+
* generation). Absent when no call in this locale reported usage: a dry-run, a token-less provider
|
|
1047
|
+
* (DeepL), or a locale with nothing to translate. Never a fabricated `{ inputTokens: 0, outputTokens: 0 }`.
|
|
1048
|
+
*/
|
|
1049
|
+
readonly usage?: UsageSummary;
|
|
969
1050
|
/**
|
|
970
1051
|
* Notices for this locale: provider notices (e.g. DeepL graceful-degradation) and SDK notices
|
|
971
1052
|
* (e.g. a target language needing more CLDR plural categories than the source supplies). Empty when
|
|
972
1053
|
* nothing was degraded or flagged.
|
|
973
1054
|
*/
|
|
974
1055
|
readonly notices: readonly LocaleNotice[];
|
|
1056
|
+
/**
|
|
1057
|
+
* Keys accepted and written this run that the review heuristics flagged for a second look, sorted
|
|
1058
|
+
* by key. Distinct from the placeholder/ICU integrity gate: a review flag is advisory only and never
|
|
1059
|
+
* withholds a key, so this never double-reports a key already surfaced through
|
|
1060
|
+
* {@link LocaleSummary.integrityMismatches} or {@link LocaleSummary.providerFailures}. Empty when
|
|
1061
|
+
* nothing was flagged, always empty for a workbook import (which never calls a provider or recomputes
|
|
1062
|
+
* flags on its own path).
|
|
1063
|
+
*/
|
|
1064
|
+
readonly needsReview: readonly NeedsReviewEntry[];
|
|
975
1065
|
/**
|
|
976
1066
|
* Present only when status is "failed": a structured, secret-free error. `code` is a PRESERVED string
|
|
977
1067
|
* (the underlying provider/adapter error's `code`, or `"LOCALE_FAILED"` as a fallback), intentionally
|
|
@@ -992,6 +1082,13 @@ interface RunSummary {
|
|
|
992
1082
|
readonly succeeded: readonly string[];
|
|
993
1083
|
/** Locales whose run failed (see each locale's `error`). */
|
|
994
1084
|
readonly failed: readonly string[];
|
|
1085
|
+
/**
|
|
1086
|
+
* Summed token usage across every locale's {@link LocaleSummary.usage}. Absent when no locale in the
|
|
1087
|
+
* run reported usage (a dry-run, or an all-token-less-provider run).
|
|
1088
|
+
*/
|
|
1089
|
+
readonly usage?: UsageSummary;
|
|
1090
|
+
/** The run-wide token-budget outcome; present only when `maxTokens` is configured. */
|
|
1091
|
+
readonly budget?: RunBudget;
|
|
995
1092
|
}
|
|
996
1093
|
|
|
997
1094
|
/** Builds the provider from its config. Injectable so tests stay offline. */
|
|
@@ -1317,4 +1414,4 @@ interface WatchController {
|
|
|
1317
1414
|
*/
|
|
1318
1415
|
declare function watch(input: WatchInput, deps?: WatchDeps): Promise<WatchController>;
|
|
1319
1416
|
|
|
1320
|
-
export { type CheckDeps, type CheckInput, type CheckSummary, type ConfigSource, type CreateProvider, type CreateWatcher, DEFAULT_WORKBOOK_PATH, type DiffDeps, type DiffInput, type DiffSummary, type ExportWorkbookDeps, type ExportWorkbookInput, type ExportWorkbookResult, type GlossaryProvenance, type ImportWorkbookDeps, type ImportWorkbookInput, LOCK_FILE_NAME, type LoadConfigOptions, type LoadLockFileDeps, type LoadLockFileInput, type LoadedConfig, type LocaleCheckSummary, type LocaleDiff, type LocaleNotice, type LocaleSummary, type LockFile, type LockLocaleState, type LockStateDeps, type LockStateInput, type LockStateResult, type ProviderConfig, type ProviderId, type RunSummary, type RunTranslate, type ScaffoldableProviderId, SdkError, type SdkErrorCode, type SdkFs, type SdkNotice, type SdkNoticeCode, type SupportedFormat$1 as SupportedFormat, type TranslateDeps, type TranslateInput, type VerbatraConfig, type VerbatraConfigInput, type WatchController, type WatchDeps, type WatchInput, type WatchRunResult, type Watcher, check, defineConfig, diff, exportWorkbook, importWorkbook, loadConfig, loadConfigWithMeta, loadLockFile, lockState, scaffoldingMetadata, translate, verbatraConfigSchema, watch };
|
|
1417
|
+
export { type BudgetBehavior, type CheckDeps, type CheckInput, type CheckSummary, type ConfigSource, type CreateProvider, type CreateWatcher, DEFAULT_WORKBOOK_PATH, type DiffDeps, type DiffInput, type DiffSummary, type ExportWorkbookDeps, type ExportWorkbookInput, type ExportWorkbookResult, type GlossaryProvenance, type ImportWorkbookDeps, type ImportWorkbookInput, LOCK_FILE_NAME, type LoadConfigOptions, type LoadLockFileDeps, type LoadLockFileInput, type LoadedConfig, type LocaleCheckSummary, type LocaleDiff, type LocaleNotice, type LocaleSummary, type LockFile, type LockLocaleState, type LockStateDeps, type LockStateInput, type LockStateResult, type NeedsReviewEntry, type ProviderConfig, type ProviderId, type ReviewReasonCode, type RunBudget, type RunSummary, type RunTranslate, type ScaffoldableProviderId, SdkError, type SdkErrorCode, type SdkFs, type SdkNotice, type SdkNoticeCode, type SupportedFormat$1 as SupportedFormat, type TranslateDeps, type TranslateInput, type UsageSummary, type VerbatraConfig, type VerbatraConfigInput, type WatchController, type WatchDeps, type WatchInput, type WatchRunResult, type Watcher, check, defineConfig, diff, exportWorkbook, importWorkbook, loadConfig, loadConfigWithMeta, loadLockFile, lockState, scaffoldingMetadata, translate, verbatraConfigSchema, watch };
|
package/dist/index.d.ts
CHANGED
|
@@ -3,19 +3,6 @@ import Anthropic from '@anthropic-ai/sdk';
|
|
|
3
3
|
import { Interactions } from '@google/genai';
|
|
4
4
|
import OpenAI from 'openai';
|
|
5
5
|
|
|
6
|
-
/** Zod schema accepting exactly one of {@link SUPPORTED_FORMATS}. */
|
|
7
|
-
declare const supportedFormatSchema$1: z.ZodEnum<{
|
|
8
|
-
"i18next-json": "i18next-json";
|
|
9
|
-
"vue-i18n-json": "vue-i18n-json";
|
|
10
|
-
"next-intl-json": "next-intl-json";
|
|
11
|
-
"ngx-translate-json": "ngx-translate-json";
|
|
12
|
-
xliff: "xliff";
|
|
13
|
-
yaml: "yaml";
|
|
14
|
-
arb: "arb";
|
|
15
|
-
}>;
|
|
16
|
-
/** One of the supported source formats; a member of {@link SUPPORTED_FORMATS}. */
|
|
17
|
-
type SupportedFormat$1 = z.infer<typeof supportedFormatSchema$1>;
|
|
18
|
-
|
|
19
6
|
/**
|
|
20
7
|
* A single, format-neutral translation unit. Placeholders are supplied already
|
|
21
8
|
* extracted; core never derives them from the value.
|
|
@@ -124,6 +111,24 @@ interface ProviderNotice {
|
|
|
124
111
|
/** A static, safe description; never a key or translatable content. */
|
|
125
112
|
readonly message: string;
|
|
126
113
|
}
|
|
114
|
+
/**
|
|
115
|
+
* Stable codes for a derived, per-key "needs review" signal. This is verbatra's own computed
|
|
116
|
+
* assessment, never a raw model self-score: four are recomputable from plain source/translated
|
|
117
|
+
* values (see the shared heuristic function), and `PROVIDER_DEGRADED` is applied by the caller from
|
|
118
|
+
* a provider notice.
|
|
119
|
+
*
|
|
120
|
+
* - `LENGTH_RATIO_OUTLIER`: the translated value's length is far shorter or longer than the source's.
|
|
121
|
+
* - `EQUALS_SOURCE`: the translated value equals the source value verbatim.
|
|
122
|
+
* - `GLOSSARY_TERM_MISSED`: a configured glossary target term did not appear in the translation.
|
|
123
|
+
* - `INTEGRITY_REORDERED`: the placeholder set matched but landed in a different order.
|
|
124
|
+
* - `PROVIDER_DEGRADED`: the batch this key came from carried a graceful-degradation notice.
|
|
125
|
+
*/
|
|
126
|
+
type ReviewReasonCode = "LENGTH_RATIO_OUTLIER" | "EQUALS_SOURCE" | "GLOSSARY_TERM_MISSED" | "INTEGRITY_REORDERED" | "PROVIDER_DEGRADED";
|
|
127
|
+
/** A key flagged for human review, carrying every reason code that applies. */
|
|
128
|
+
interface ReviewFlag {
|
|
129
|
+
readonly status: "review";
|
|
130
|
+
readonly reasons: readonly ReviewReasonCode[];
|
|
131
|
+
}
|
|
127
132
|
/** Result of a batch translation: per-key values, per-key integrity outcomes, and any notices. */
|
|
128
133
|
interface TranslateResult {
|
|
129
134
|
/** The translated value for each requested key. */
|
|
@@ -138,6 +143,11 @@ interface TranslateResult {
|
|
|
138
143
|
* report returns an empty array rather than omitting the field.
|
|
139
144
|
*/
|
|
140
145
|
readonly notices?: readonly ProviderNotice[];
|
|
146
|
+
/**
|
|
147
|
+
* Derived per-key review flags for this batch. A key absent from the map is implicitly "ok"; a
|
|
148
|
+
* present key carries one or more {@link ReviewReasonCode}s. Optional and additive.
|
|
149
|
+
*/
|
|
150
|
+
readonly reviewFlags?: ReadonlyMap<string, ReviewFlag>;
|
|
141
151
|
}
|
|
142
152
|
/**
|
|
143
153
|
* The single contract every provider implements. It is narrow enough that a machine-translation API like
|
|
@@ -212,6 +222,19 @@ type GeminiModel = Interactions.Model;
|
|
|
212
222
|
*/
|
|
213
223
|
type OpenAiModel = OpenAI.ChatModel;
|
|
214
224
|
|
|
225
|
+
/** Zod schema accepting exactly one of {@link SUPPORTED_FORMATS}. */
|
|
226
|
+
declare const supportedFormatSchema$1: z.ZodEnum<{
|
|
227
|
+
"i18next-json": "i18next-json";
|
|
228
|
+
"vue-i18n-json": "vue-i18n-json";
|
|
229
|
+
"next-intl-json": "next-intl-json";
|
|
230
|
+
"ngx-translate-json": "ngx-translate-json";
|
|
231
|
+
xliff: "xliff";
|
|
232
|
+
yaml: "yaml";
|
|
233
|
+
arb: "arb";
|
|
234
|
+
}>;
|
|
235
|
+
/** One of the supported source formats; a member of {@link SUPPORTED_FORMATS}. */
|
|
236
|
+
type SupportedFormat$1 = z.infer<typeof supportedFormatSchema$1>;
|
|
237
|
+
|
|
215
238
|
/**
|
|
216
239
|
* The provider section of the config: a discriminated union over the provider id, reusing each
|
|
217
240
|
* provider's own config schema. There is no key field anywhere in this union except
|
|
@@ -314,6 +337,11 @@ declare const verbatraConfigSchema: z.ZodObject<{
|
|
|
314
337
|
prune: z.ZodOptional<z.ZodBoolean>;
|
|
315
338
|
generatePlurals: z.ZodOptional<z.ZodBoolean>;
|
|
316
339
|
maxBatchSize: z.ZodOptional<z.ZodNumber>;
|
|
340
|
+
maxTokens: z.ZodOptional<z.ZodNumber>;
|
|
341
|
+
budgetBehavior: z.ZodOptional<z.ZodEnum<{
|
|
342
|
+
warn: "warn";
|
|
343
|
+
stop: "stop";
|
|
344
|
+
}>>;
|
|
317
345
|
}, z.core.$strict>;
|
|
318
346
|
/**
|
|
319
347
|
* The as-authored (or as-parsed) shape of the verbatra configuration, straight from the schema: `glossary`
|
|
@@ -623,6 +651,13 @@ interface ReadResult {
|
|
|
623
651
|
readonly resource: LocaleResource;
|
|
624
652
|
/** Keys whose values are invalid for the format's message syntax. Empty for non-ICU formats. */
|
|
625
653
|
readonly invalidIcuKeys: readonly string[];
|
|
654
|
+
/**
|
|
655
|
+
* Dotted paths of leaves that were present in the source but excluded because they are not
|
|
656
|
+
* strings (a stray number, boolean, or null). These are never translated, hashed, diffed, or
|
|
657
|
+
* checked for placeholder or ICU integrity, and are not written back if the file is later
|
|
658
|
+
* rewritten. Empty for a file with no such leaves.
|
|
659
|
+
*/
|
|
660
|
+
readonly excludedLeafPaths: readonly string[];
|
|
626
661
|
}
|
|
627
662
|
/**
|
|
628
663
|
* The contract every format adapter implements. A new format attaches by implementing this interface
|
|
@@ -907,7 +942,32 @@ interface LockStateDeps {
|
|
|
907
942
|
declare function lockState(input: LockStateInput, deps?: LockStateDeps): Promise<LockStateResult>;
|
|
908
943
|
|
|
909
944
|
/** A stable code for an SDK-originated notice (not a provider notice). */
|
|
910
|
-
type SdkNoticeCode = "PLURAL_CATEGORIES_INCOMPLETE" | "SUB_BATCH_FAILED" | "BLANK_ROW_BASELINE_RETAINED";
|
|
945
|
+
type SdkNoticeCode = "PLURAL_CATEGORIES_INCOMPLETE" | "SUB_BATCH_FAILED" | "BLANK_ROW_BASELINE_RETAINED" | "BUDGET_TOKENS_EXCEEDED";
|
|
946
|
+
/** Summed token usage across every provider call in a scope (one locale, or the whole run). */
|
|
947
|
+
interface UsageSummary {
|
|
948
|
+
readonly inputTokens: number;
|
|
949
|
+
readonly outputTokens: number;
|
|
950
|
+
}
|
|
951
|
+
/** The configured token-budget behavior: warn and continue, or stop making further provider calls. */
|
|
952
|
+
type BudgetBehavior = "warn" | "stop";
|
|
953
|
+
/**
|
|
954
|
+
* The run-wide token-budget outcome, present on {@link RunSummary} only when `maxTokens` is configured.
|
|
955
|
+
* `supported: false` means the configured provider never reported usage in this run (a token-less
|
|
956
|
+
* provider such as DeepL, or a dry-run): the guardrail is honestly inert, `tokensUsed` stays `0`, and
|
|
957
|
+
* `exceeded` stays `false`, never a false trip.
|
|
958
|
+
*/
|
|
959
|
+
interface RunBudget {
|
|
960
|
+
/** The configured ceiling. */
|
|
961
|
+
readonly maxTokens: number;
|
|
962
|
+
/** The configured behavior once the ceiling is reached. */
|
|
963
|
+
readonly behavior: BudgetBehavior;
|
|
964
|
+
/** Whether the configured provider reported usage at all this run. */
|
|
965
|
+
readonly supported: boolean;
|
|
966
|
+
/** Cumulative input plus output tokens across the run so far. */
|
|
967
|
+
readonly tokensUsed: number;
|
|
968
|
+
/** Whether `tokensUsed` reached or passed `maxTokens` at any point this run. */
|
|
969
|
+
readonly exceeded: boolean;
|
|
970
|
+
}
|
|
911
971
|
/**
|
|
912
972
|
* A notice raised by the SDK itself (not a provider), structurally identical to a {@link ProviderNotice}
|
|
913
973
|
* so both share the {@link LocaleSummary.notices} channel. Carries only a stable code and a static,
|
|
@@ -921,6 +981,13 @@ interface SdkNotice {
|
|
|
921
981
|
}
|
|
922
982
|
/** A notice on a locale summary: either a provider-emitted notice or an SDK-emitted one. */
|
|
923
983
|
type LocaleNotice = ProviderNotice | SdkNotice;
|
|
984
|
+
/** One key flagged for human review, and every reason code that applies to it. */
|
|
985
|
+
interface NeedsReviewEntry {
|
|
986
|
+
/** The flagged key. */
|
|
987
|
+
readonly key: string;
|
|
988
|
+
/** Every {@link ReviewReasonCode} that applies to this key. */
|
|
989
|
+
readonly reasons: readonly ReviewReasonCode[];
|
|
990
|
+
}
|
|
924
991
|
/** Structured outcome for one target locale; surfaced as data on the run, never thrown. */
|
|
925
992
|
interface LocaleSummary {
|
|
926
993
|
/** The target locale this summary is for. */
|
|
@@ -966,12 +1033,35 @@ interface LocaleSummary {
|
|
|
966
1033
|
* and acted, and empty in a dry-run.
|
|
967
1034
|
*/
|
|
968
1035
|
readonly generated: readonly string[];
|
|
1036
|
+
/**
|
|
1037
|
+
* Candidate keys never sent to the provider because a configured `maxTokens` budget already tripped
|
|
1038
|
+
* in `"stop"` mode: keys remaining in the current locale once the ceiling was crossed, and every
|
|
1039
|
+
* candidate key of a later, fully-skipped locale. Always present, empty by default, same convention as
|
|
1040
|
+
* {@link LocaleSummary.integrityMismatches} and {@link LocaleSummary.providerFailures}. Each key keeps
|
|
1041
|
+
* its prior lock hash and is picked up again next run, exactly like a `providerFailures` key.
|
|
1042
|
+
*/
|
|
1043
|
+
readonly budgetWithheld: readonly string[];
|
|
1044
|
+
/**
|
|
1045
|
+
* Summed token usage across every provider call for this locale (main translation plus plural
|
|
1046
|
+
* generation). Absent when no call in this locale reported usage: a dry-run, a token-less provider
|
|
1047
|
+
* (DeepL), or a locale with nothing to translate. Never a fabricated `{ inputTokens: 0, outputTokens: 0 }`.
|
|
1048
|
+
*/
|
|
1049
|
+
readonly usage?: UsageSummary;
|
|
969
1050
|
/**
|
|
970
1051
|
* Notices for this locale: provider notices (e.g. DeepL graceful-degradation) and SDK notices
|
|
971
1052
|
* (e.g. a target language needing more CLDR plural categories than the source supplies). Empty when
|
|
972
1053
|
* nothing was degraded or flagged.
|
|
973
1054
|
*/
|
|
974
1055
|
readonly notices: readonly LocaleNotice[];
|
|
1056
|
+
/**
|
|
1057
|
+
* Keys accepted and written this run that the review heuristics flagged for a second look, sorted
|
|
1058
|
+
* by key. Distinct from the placeholder/ICU integrity gate: a review flag is advisory only and never
|
|
1059
|
+
* withholds a key, so this never double-reports a key already surfaced through
|
|
1060
|
+
* {@link LocaleSummary.integrityMismatches} or {@link LocaleSummary.providerFailures}. Empty when
|
|
1061
|
+
* nothing was flagged, always empty for a workbook import (which never calls a provider or recomputes
|
|
1062
|
+
* flags on its own path).
|
|
1063
|
+
*/
|
|
1064
|
+
readonly needsReview: readonly NeedsReviewEntry[];
|
|
975
1065
|
/**
|
|
976
1066
|
* Present only when status is "failed": a structured, secret-free error. `code` is a PRESERVED string
|
|
977
1067
|
* (the underlying provider/adapter error's `code`, or `"LOCALE_FAILED"` as a fallback), intentionally
|
|
@@ -992,6 +1082,13 @@ interface RunSummary {
|
|
|
992
1082
|
readonly succeeded: readonly string[];
|
|
993
1083
|
/** Locales whose run failed (see each locale's `error`). */
|
|
994
1084
|
readonly failed: readonly string[];
|
|
1085
|
+
/**
|
|
1086
|
+
* Summed token usage across every locale's {@link LocaleSummary.usage}. Absent when no locale in the
|
|
1087
|
+
* run reported usage (a dry-run, or an all-token-less-provider run).
|
|
1088
|
+
*/
|
|
1089
|
+
readonly usage?: UsageSummary;
|
|
1090
|
+
/** The run-wide token-budget outcome; present only when `maxTokens` is configured. */
|
|
1091
|
+
readonly budget?: RunBudget;
|
|
995
1092
|
}
|
|
996
1093
|
|
|
997
1094
|
/** Builds the provider from its config. Injectable so tests stay offline. */
|
|
@@ -1317,4 +1414,4 @@ interface WatchController {
|
|
|
1317
1414
|
*/
|
|
1318
1415
|
declare function watch(input: WatchInput, deps?: WatchDeps): Promise<WatchController>;
|
|
1319
1416
|
|
|
1320
|
-
export { type CheckDeps, type CheckInput, type CheckSummary, type ConfigSource, type CreateProvider, type CreateWatcher, DEFAULT_WORKBOOK_PATH, type DiffDeps, type DiffInput, type DiffSummary, type ExportWorkbookDeps, type ExportWorkbookInput, type ExportWorkbookResult, type GlossaryProvenance, type ImportWorkbookDeps, type ImportWorkbookInput, LOCK_FILE_NAME, type LoadConfigOptions, type LoadLockFileDeps, type LoadLockFileInput, type LoadedConfig, type LocaleCheckSummary, type LocaleDiff, type LocaleNotice, type LocaleSummary, type LockFile, type LockLocaleState, type LockStateDeps, type LockStateInput, type LockStateResult, type ProviderConfig, type ProviderId, type RunSummary, type RunTranslate, type ScaffoldableProviderId, SdkError, type SdkErrorCode, type SdkFs, type SdkNotice, type SdkNoticeCode, type SupportedFormat$1 as SupportedFormat, type TranslateDeps, type TranslateInput, type VerbatraConfig, type VerbatraConfigInput, type WatchController, type WatchDeps, type WatchInput, type WatchRunResult, type Watcher, check, defineConfig, diff, exportWorkbook, importWorkbook, loadConfig, loadConfigWithMeta, loadLockFile, lockState, scaffoldingMetadata, translate, verbatraConfigSchema, watch };
|
|
1417
|
+
export { type BudgetBehavior, type CheckDeps, type CheckInput, type CheckSummary, type ConfigSource, type CreateProvider, type CreateWatcher, DEFAULT_WORKBOOK_PATH, type DiffDeps, type DiffInput, type DiffSummary, type ExportWorkbookDeps, type ExportWorkbookInput, type ExportWorkbookResult, type GlossaryProvenance, type ImportWorkbookDeps, type ImportWorkbookInput, LOCK_FILE_NAME, type LoadConfigOptions, type LoadLockFileDeps, type LoadLockFileInput, type LoadedConfig, type LocaleCheckSummary, type LocaleDiff, type LocaleNotice, type LocaleSummary, type LockFile, type LockLocaleState, type LockStateDeps, type LockStateInput, type LockStateResult, type NeedsReviewEntry, type ProviderConfig, type ProviderId, type ReviewReasonCode, type RunBudget, type RunSummary, type RunTranslate, type ScaffoldableProviderId, SdkError, type SdkErrorCode, type SdkFs, type SdkNotice, type SdkNoticeCode, type SupportedFormat$1 as SupportedFormat, type TranslateDeps, type TranslateInput, type UsageSummary, type VerbatraConfig, type VerbatraConfigInput, type WatchController, type WatchDeps, type WatchInput, type WatchRunResult, type Watcher, check, defineConfig, diff, exportWorkbook, importWorkbook, loadConfig, loadConfigWithMeta, loadLockFile, lockState, scaffoldingMetadata, translate, verbatraConfigSchema, watch };
|