i18n

type CRUD[T any, ID comparable] struct {
	// contains filtered or unexported fields
}

type IDFunc[T any, ID comparable] func(entity T) ID

type Option[T any, ID comparable] func(*Options[T, ID])

type Options[T any, ID comparable] struct {
	// EntityType names this entity type in Translation rows. If empty, it is
	// derived from the struct type T (e.g. Location -> "locations").
	EntityType string

	// Fields lists the storage names of the translatable fields (db-tag
	// names, e.g. "title", "description"). Required; every name must resolve
	// to a string field on T.
	Fields []string

	// IDFunc extracts the primary key from an entity. Required.
	IDFunc IDFunc[T, ID]

	// Preloads declares which preloaded relations carry translatable text, so the
	// overlay reaches a parent's children and not just the parent. Empty by
	// default: a relation is translated only when declared.
	Preloads []Translated

	// ExcludeStale hides stale translations on reads, falling back to source text.
	// Default: stale translations are served (usually better than the wrong
	// language).
	ExcludeStale bool

	// SkipOverlay disables the read overlay: Get/List return source text untouched
	// while Update/Patch still mark translations stale. For editor/admin repos,
	// where the form shows and saves source text but source edits must still
	// invalidate translations - the safe answer to the read-modify-write hazard in
	// the package doc.
	SkipOverlay bool

	// DeleteWithEntity removes an entity's translations when it is deleted. Default
	// false: keeping them is the safe choice with soft-deleted, restorable entities.
	DeleteWithEntity bool

	// ErrorHandler is invoked when a best-effort side operation fails (overlay read,
	// staleness patch, delete cleanup). If nil, failures are logged via slog.
	// Reads/mutations themselves never fail over it.
	ErrorHandler func(error)
}

type Source string

type Translated struct {
	// contains filtered or unexported fields
}

type Translation struct {
	// ID is the unique identifier for this translation row (UUID).
	ID string `json:"id" db:"id,pk" bson:"_id"`

	// EntityType names the translated entity's type (e.g. "locations",
	// "videos"). Derived from the struct type or set via WithEntityType.
	EntityType string `json:"entity_type" db:"entity_type" bson:"entity_type"`

	// EntityID is the primary key of the translated entity, stringified.
	EntityID string `json:"entity_id" db:"entity_id" bson:"entity_id"`

	// Field is the storage name of the translated field (e.g. "title") -
	// the db tag of the struct field, or its snake_cased Go name.
	Field string `json:"field" db:"field" bson:"field"`

	// Lang is the language tag of Value (matches r3.GetLocale values).
	Lang string `json:"lang" db:"lang" bson:"lang"`

	// Value is the translated text. An empty Value is treated as "no
	// translation" and never overlaid.
	Value string `json:"value" db:"value" bson:"value"`

	// ValueNorm is an optional normalized copy of Value for search (case/diacritics
	// folded as the app defines). R3 never computes or reads it; it exists so
	// translated content is searchable with the app's own normalization.
	ValueNorm string `json:"value_norm,omitempty" db:"value_norm" bson:"value_norm,omitempty"`

	// Source records who produced this translation: ai, human, or import.
	Source Source `json:"source" db:"source" bson:"source"`

	// Model optionally names the model that produced an AI translation.
	Model string `json:"model,omitempty" db:"model" bson:"model,omitempty"`

	// SourceHash is Hash() of the source text this translation was made
	// from. The decorator compares it against the current source text on
	// Update/Patch to detect staleness.
	SourceHash string `json:"source_hash" db:"source_hash" bson:"source_hash"`

	// Stale is set when the source text changed after this translation was
	// made. Stale translations are still served by default (see
	// WithoutStale) and form the re-translation queue for workers.
	Stale bool `json:"stale" db:"stale" bson:"stale"`

	// CreatedAt is when this translation row was first written.
	CreatedAt time.Time `json:"created_at" db:"created_at" bson:"created_at"`

	// UpdatedAt is when Value was last (re)written.
	UpdatedAt time.Time `json:"updated_at" db:"updated_at" bson:"updated_at"`
}