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]

	// ExcludeStale hides stale translations on reads, falling back to the
	// source text, instead of serving the outdated translation (default:
	// stale translations are served — usually better than the wrong
	// language).
	ExcludeStale bool

	// SkipOverlay disables the read overlay entirely: Get/List return source
	// text untouched while Update/Patch still mark translations stale. Use it
	// on editor/admin repositories, where the form must show (and save) the
	// source text but source edits still need to invalidate translations —
	// this is the safe answer to the read-modify-write hazard in the package
	// doc.
	SkipOverlay bool

	// DeleteWithEntity removes an entity's translations when the entity is
	// deleted. Default false: translations are kept, which is the safe
	// choice with soft-deleted entities that may be restored.
	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 because of it.
	ErrorHandler func(error)
}

type Source string

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
	// (fold case/diacritics as the application defines). R3 never computes
	// or reads it — it exists so translated content is searchable with the
	// same normalization the application applies to source text.
	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"`
}