Documentation
¶
Overview ¶
Package translate serves POST /v1/translate — the ONE translation surface, two tiers behind one endpoint, one auth path, one meter (HIP-0516).
POST /v1/translate { text | batch[], target, source?, tier?, glossary?, format? }
-> { translations[], detected_source?, tier, usage }
`tier` picks the engine and defaults to quality:
- quality routes to the model plane (deps.AI — zen through the gateway), which carries context, terminology and tone.
- bulk routes to MADLAD-400 under CTranslate2 (engine.go), for high-volume, low-latency work where a model is overkill. A deployment with no bulk backend answers 503; bulk NEVER falls back to quality, so a caller is never quietly served — or charged — at a tier it did not ask for.
The translation memory (memory.go) is NORMATIVE, not a cache. Every string keys on (source_text, target, glossary_version, tier); a hit returns the stored value unchanged, so only new or changed source strings reach an engine. That is what makes a locale rebuild idempotent under a non-deterministic model, and it is what makes the bill proportional to what actually changed.
The review lane rides the same memory: an entry carries a state on the ladder machine -> suggested -> approved -> published, and human work is IMMUNE to machine churn (memory.put). A rebuild can never silently revert an approved string.
Tenancy: org-scoped by the validated principal. The memory is a per-org SQLite file (HIP-0302 physical isolation), so a request cannot reach another org's memory. Submitted text is customer content, held only in that org's own memory.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrNoEngine = errors.New("translate: tier backend not configured")
ErrNoEngine marks a tier whose backend this deployment does not serve. The handler renders it 503 for that tier and never re-routes to another one.
Functions ¶
Types ¶
type Engine ¶
Engine translates a job's strings into one target language. Two implementations, one per tier; the endpoint, the memory, and the meter are shared.
type Entry ¶
type Entry struct {
Source string `json:"source"`
Target string `json:"target"`
Tier Tier `json:"tier"`
// Glossary is the glossary VERSION the entry was translated under — the digest
// version() derives from the terms, so changing a term changes the key and the
// stale rendering can never be served.
Glossary string `json:"glossary_version,omitempty"`
Text string `json:"text"`
State State `json:"state"`
Actor string `json:"actor,omitempty"`
UpdatedAt int64 `json:"updated_at"`
}
Entry is one remembered translation. Source+Target+Tier+Glossary are its identity (the HIP-0516 tuple); Text and State are what the lane holds.
type Format ¶
type Format string
Format tells an engine what markup the source carries so placeholders and tags survive the round trip.
type Job ¶
type Job struct {
Texts []string
Source string // "" ⇒ the engine detects and reports it
Target string
Format Format
Glossary map[string]string
Org string // the effective org — the data scope
BillingOrg string // the home org that pays
Project string
}
Job is one engine call: the strings to translate plus the billing scope, carried on the value exactly as types.ChatRequest carries it, so an engine can never run unattributed.
type Request ¶
type Request struct {
Text string `json:"text"`
Batch []string `json:"batch"`
Target string `json:"target"`
Source string `json:"source"`
Tier Tier `json:"tier"`
Glossary map[string]string `json:"glossary"`
Format Format `json:"format"`
}
Request is the POST /v1/translate body. Exactly one of Text or Batch carries the work; Batch preserves order in the reply.
type Response ¶
type Response struct {
Translations []Translation `json:"translations"`
DetectedSource string `json:"detected_source,omitempty"`
Tier Tier `json:"tier"`
Usage Usage `json:"usage"`
}
Response is the POST /v1/translate reply.
type Result ¶
Result is one engine call's answer: one translation per input, in input order, plus the language the engine detected when the caller named none.
type ReviewRequest ¶
type ReviewRequest struct {
Source string `json:"source"`
Target string `json:"target"`
Tier Tier `json:"tier"`
Glossary map[string]string `json:"glossary"`
Text string `json:"text"`
State State `json:"state"`
}
ReviewRequest is the human write: the same tuple a translate call carries, plus the reviewed text and its new position on the ladder.
type Translation ¶
type Translation struct {
Source string `json:"source"`
Text string `json:"text"`
State State `json:"state"`
Cached bool `json:"cached"`
}
Translation is one string's result: the translation, where on the review ladder it sits, and whether it came from the memory rather than an engine.
type Usage ¶
type Usage struct {
Strings int `json:"strings"`
Cached int `json:"cached"`
Translated int `json:"translated"`
Characters int `json:"characters"`
}
Usage reports what the call actually did — real counts, never an estimate. Characters counts only the source that REACHED an engine, which is what the bulk tier bills on; a fully-cached rebuild therefore reports (and costs) zero.
Source Files