logger

type GenderCategory = i18n.GenderCategory

type Level int

type LeveledLogger interface {
	// Debug logs a debug-level message with optional format arguments.
	// Debug messages are for detailed debugging information.
	Debug(msg string, args ...any)

	// Info logs an info-level message with optional format arguments.
	// Info messages are for general informational messages.
	Info(msg string, args ...any)

	// Warn logs a warn-level message with optional format arguments.
	// Warn messages indicate potential issues that should be investigated.
	Warn(msg string, args ...any)

	// Error logs an error-level message with optional format arguments.
	// Error messages indicate failures that need attention.
	Error(msg string, args ...any)

	// Fatal logs a fatal-level message with optional format arguments.
	// Fatal messages indicate critical errors. Implementations may choose
	// to terminate the program after logging a fatal message.
	Fatal(msg string, args ...any)
}

type Logger interface {
	// LeveledLogger provides the core logging methods.
	LeveledLogger

	// WithFields returns a new Logger with additional structured fields.
	// Fields are provided as key-value pairs: ("user_id", 123, "action", "login").
	// Implementations should merge fields from parent loggers.
	WithFields(fields ...any) Logger

	// WithContext returns a new Logger with the given context.
	// Implementations can extract values from context such as trace IDs,
	// correlation IDs, or request-scoped values.
	WithContext(ctx context.Context) Logger

	// WithLevel returns a new Logger that only logs at or above the given level.
	// Messages below this level should be silently discarded.
	WithLevel(level Level) Logger

	// Enabled returns true if logging at the given level would produce output.
	// Use this to avoid expensive computation for disabled log levels:
	//
	//	if log.Enabled(LevelDebug) {
	//	    log.Debug("expensive: %v", computeExpensiveValue())
	//	}
	Enabled(level Level) bool
}

type NopLogger struct{}

type TranslatorProvider interface {
	// Translate returns the translated string for the given key.
	Translate(key string) string

	// TranslateWithArgs returns translated string with format arguments.
	TranslateWithArgs(key string, args ...interface{}) string

	// TranslatePlural returns count-dependent translation for the given key.
	TranslatePlural(key string, count interface{}) string

	// TranslateGender returns gender-aware translation for the given key.
	TranslateGender(key string, gender GenderCategory) string

	// HasKey returns true if the translation key exists.
	HasKey(key string) bool

	// SetLocale changes the current locale.
	SetLocale(locale string)

	// GetLocale returns the current locale.
	GetLocale() string
}