@shubhamdeol/locale-ota-ai
v1.0.0
Published
Prompt builder, the generateText call, provider registry, usage capture.
Readme
@shubhamdeol/locale-ota-ai
The translation engine: the provider registry, the prompt builder, the batch call, the
validator and the job runner. It knows nothing about HTTP and nothing about Postgres. It
talks to a JobStore the server implements, so the same engine runs in a route, in a
worker or in a test.
Status: phase 3. Version 0.0.0, unpublished.
Install
bun add @shubhamdeol/locale-ota-aiProviders
resolveModel(spec) turns a spec string into an AI SDK LanguageModel. No model id is
hardcoded in this package, so a new model needs no release.
| Spec | Factory | API key variable |
| --- | --- | --- |
| google:<model-id> | google() from @ai-sdk/google | GOOGLE_GENERATIVE_AI_API_KEY |
| openai:<model-id> | openai() from @ai-sdk/openai | OPENAI_API_KEY, and OPENAI_BASE_URL when set |
| a LanguageModel object | passes through | whatever that provider reads |
| anything else | — | throws AiError with code unknown_provider |
Both variables were read out of the installed packages, @ai-sdk/[email protected] and
@ai-sdk/[email protected]. Neither provider reads its key when the model is built, only when
a request is sent, so resolveModel never throws for a missing key and a dashboard can
show the model choice without credentials. PROVIDER_KEY_VARIABLES exports the same table.
The public API
| Export | What it does |
| --- | --- |
| resolveModel(spec) | The spec table above. describeModel(spec) names a model for jobs.model. |
| buildPrompt({ app, language, format, items }) | { system, prompt } for one batch. |
| translateBatch({ model, app, language, format, items, signal? }) | One model call: { results, usage, raw }. |
| validateResults({ items, results, format }) | { accepted, rejected } through core validateTranslation. |
| buildFixItems(rejected, items) | The items to ask again, each quoting its errors. |
| planWork({ releaseKeys, sourceValues, existing, language, only? }) | The work items one language is missing. |
| runJob(options) | The whole job: plan, batch, call, validate, fix, write, resume. |
| memoryJobStore() | A JobStore in memory, for tests and as the reference. |
| AiError | The one error type: a code string and a details object. |
Every item is either plain or plural:
{ kind: "plain", namespace, key, sourceHash, source, context? }
{ kind: "plural", namespace, key, sourceHash, source, context?,
ordinal, forms: { one, other }, needed: ["zero", ...], sourceHashes: { zero, ... } }sourceValues is a flat map keyed by sourceKey(namespace, key), which joins the two with
a NUL byte. existing is the list of { namespace, key, sourceHash } the language already
holds, of any origin, which is why a human override is never re-asked: it is simply a row.
How a batch flows
planWork -> batchWork -> claimBatch -> translateBatch -> validateResults
| |
| rejected? buildFixItems
| |
| translateBatch again
v v
insertTranslations insertFlags
|
markBatch done
|
updateJobCounts + onProgressPlan.
planWorkasks for every release key with no row at the same source hash, and for every plural group that still misses a target form. A changed English value has a new hash, so it is asked again; an unchanged one never is.only, onplanWorkand onrunJob, narrows the plan to the keys it names and asks for them whatever rows they already hold. That is the dashboard's "retranslate one key": without it a key with a row, human or not, is never asked again, which is the point ofexisting. A plural group is named by any of its form keys or by its base, and the whole group is then asked for every category the language needs. The written row is a new append-only row at a higher revision, so it supersedes the one that stood, a human override included: naming a key is an explicit instruction to replace it.Batch. Core
batchWorksplits the list at 150 items or 8 KB of English text, in order, so the same input always splits the same way. Onejob_batchesrow per batch.Claim. Each of
concurrencyworkers takes one pending batch at a time throughstore.claimBatch(jobId), which must be atomic in the store: in Postgres that is oneUPDATE ... WHERE id IN (SELECT ... FOR UPDATE SKIP LOCKED) RETURNING *.Call. One
generateTextcall withoutput: Output.object({ schema }), where the schema is a zod object built for this batch: every item id is a required property, a string for a plain key and an object of the needed plural categories for a plural base. The item id isnamespace:key, plus#ordinalfor an ordinal group, so the model answers under keys it can read. Usage comes back asinputTokensandoutputTokens.Validate. Core
validateTranslationchecks every value and every plural form: markers as a set, HTML tags as a multiset, no empty value. A plural item is all or nothing, so it never lands half translated.Fix. One more call for whatever was rejected, each item carrying a
contextline that quotes the errors. Anything still rejected gets aflagsrow and no translation row, so the client falls back to English for that key.Write.
insertTranslationswith originai, the job id and the batch id. The revision is assigned by the store, because it is the next value of a per-app counter and only the database can hand it out without a race.Report.
updateJobCountsandonProgressafter every batch.
Retries are the runner's, not the SDK's: translateBatch passes maxRetries: 0 so that
one batch attempt is one request. A retryable error waits 1 s, then 4 s, then 16 s, each
with half jitter, up to retries attempts; after that the batch is failed and the other
batches carry on. An error counts as retryable when the SDK's APICallError.isRetryable
says so, or the status is 408, 409, 429 or 5xx, or an APICallError carries no status at
all, which is a network error. A schema mismatch is not retryable: if the model cannot fill
the shape it was given, the batch fails and the dashboard shows why.
A job with any failed batch ends failed, otherwise done.
Counts
keysTotal, keysDone and keysFlagged are in work items, counted across every
language. A plural base is one item however many forms it produces. With no failed batch,
keysDone + keysFlagged === keysTotal; a failed batch's items are neither, because nothing
was written and nothing was flagged for them.
Resume and cancel
The job is a row and every batch is a row, so a run is resumable.
- A run with no
jobIdcallsfindOpenJob({ appId, releaseId, languages }). An open job,pendingorrunning, is picked up: its batches already exist and are not planned again. - On start,
resetStaleBatches(jobId, staleAfterMs)putsrunningbatches older than ten minutes back topending, which is how the batches of a killed process come back. - The
signalis checked before every claim and handed to every request. A run stopped by its signal leaves the jobrunningand releases the batch it was holding back topending, so the next run finishes the job rather than failing it.
The JobStore
interface JobStore {
createJob(input: CreateJobInput): Promise<Job>;
getJob(id: string): Promise<Job | null>;
findOpenJob(query: FindOpenJobQuery): Promise<Job | null>;
createBatches(jobId: string, batches: readonly NewJobBatch[]): Promise<JobBatch[]>;
listBatches(jobId: string): Promise<JobBatch[]>;
claimBatch(jobId: string): Promise<JobBatch | null>;
markBatch(id: string, status: BatchStatus, options?: MarkBatchOptions): Promise<void>;
resetStaleBatches(jobId: string, staleAfterMs: number): Promise<number>;
insertTranslations(rows: readonly InsertTranslationRow[]): Promise<void>;
insertFlags(flags: readonly Flag[]): Promise<void>;
updateJobCounts(jobId: string, counts: JobCounts): Promise<void>;
finishJob(jobId: string, status: JobStatus): Promise<void>;
}Job, JobBatch and Flag are the columns of plan section 4 in camel case. JobCounts
is a partial of the five jobs counters. InsertTranslationRow is a core TranslationRow
without its revision, plus appId, jobId and batchId.
Rules the store must keep:
claimBatchis atomic. Two workers, or two processes, never get the same batch.createJobhonours the status the caller asks for. The runner asks forrunning.insertTranslationsassigns one revision per call, the next value of the app's counter.markBatch(id, "pending")releases a claim: clearstarted_at, keepattempts.listBatchesis read-only. The dashboard needs it anyway for per-batch errors and tokens.
Plurals
Core pluralWork gives the English forms a release ships and the target forms a language
needs, from Intl.PluralRules. An English pair becomes six keys for Arabic and one for
Japanese. The engine writes one row per generated category, keyed with core pluralKey, so
entry_zero, entry_one and the rest.
A generated row is filed under the source hash of the English form it was translated from:
its own category when the release ships it, otherwise the other form. That keeps the
overlapping categories, one and other for most languages, composable against the
release key set without any change to core compose.
Tests
bun test packages/ai # from the repository root
bun run typecheck # from this folder
bun run build # from this folderEvery test uses MockLanguageModelV4 from ai/test. Nothing in this package's tests
reaches a provider. src/fake-model.ts is the mock: it reads the batch out of the prompt
and answers [<language>] <source> for every key, keeping every marker and tag, filling
every needed plural category, and it can be told to drop a marker once, to drop one every
time, or to throw a retryable error. It is test support and is not exported from the
package entry.
The runner tests take their 2,000 key release from the core fixture generator at
packages/core/test/fixtures/generate.ts.
