translate

type Engine interface {
	Translate(ctx context.Context, j Job) (Result, error)
}

type Format string

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
}

type MemoryEntry struct {
	// Source is the ORIGINAL string this entry translates. Part of the identity.
	Source string `json:"source"`
	// Target is the target language tag (BCP-47, e.g. "es" or "pt-BR"). Part of the
	// identity.
	Target string `json:"target"`
	// Tier is the engine tier the entry belongs to, quality or bulk. Part of the
	// identity: the two tiers keep separate renderings of the same source.
	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 is the stored translation. A memory hit returns it verbatim, which is the
	// idempotence contract.
	Text string `json:"text"`
	// State is the entry's position on the review ladder: machine, suggested,
	// approved or published.
	State State `json:"state"`
	// Actor is the validated user id that last wrote this entry by hand. Empty on an
	// entry an engine produced, and on one written before attribution existed.
	Actor string `json:"actor,omitempty"`
	// UpdatedAt is the unix second the entry last changed.
	UpdatedAt int64 `json:"updated_at"`
}

type MemoryPage struct {
	// Data is the matching memory entries, newest first.
	Data []MemoryEntry `json:"data"`
}

type MemoryQuery struct {
	// Target narrows to one target language tag (BCP-47, e.g. "es" or "pt-BR").
	Target string `json:"target"`
	// State narrows to one position on the review ladder: machine, suggested,
	// approved or published.
	State State `json:"state"`
	// Limit caps the rows returned. Non-positive or unparseable means the server
	// default (200); the ceiling is 1000.
	Limit int `json:"limit"`
}

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"`
}

type Response struct {
	Translations   []Translation `json:"translations"`
	DetectedSource string        `json:"detected_source,omitempty"`
	Tier           Tier          `json:"tier"`
	Usage          Usage         `json:"usage"`
}

type Result struct {
	Texts    []string
	Detected string
}

type ReviewRequest struct {
	// Source is the ORIGINAL string this entry translates. Required; part of the
	// entry's identity, so a different source is a different entry.
	Source string `json:"source"`
	// Target is the target language tag (BCP-47, e.g. "es" or "pt-BR"). Required;
	// part of the entry's identity.
	Target string `json:"target"`
	// Tier is the engine tier the entry belongs to, quality (the default) or bulk.
	// Part of the entry's identity: the two tiers keep separate renderings.
	Tier Tier `json:"tier"`
	// Glossary is the terminology the entry was translated under. Its VERSION — the
	// digest of the sorted terms — is part of the entry's identity, so editing a term
	// yields a new entry rather than overwriting the old rendering.
	Glossary map[string]string `json:"glossary"`
	// Text is the reviewed translation to store. A human write always wins over the
	// stored value.
	Text string `json:"text"`
	// State is the entry's new position on the review ladder: suggested, approved or
	// published. `machine` is engine-only and is refused here — a human may not demote
	// a string back into the churn.
	State State `json:"state"`
}

type State string

type Tier string

type Translation struct {
	Source string `json:"source"`
	Text   string `json:"text"`
	State  State  `json:"state"`
	Cached bool   `json:"cached"`
}

type Usage struct {
	Strings    int `json:"strings"`
	Cached     int `json:"cached"`
	Translated int `json:"translated"`
	Characters int `json:"characters"`
}