valid8

README

valid8

[!CAUTION] AI Disclaimer: This README, the documentation, unit tests and even the translations were generated by an AI that's probably smarter than me but definitely less handsome. However, the structure, logic, and core usage were all hand-crafted by a human with a soul and a caffeine addiction. Use with confidence, but if it starts speaking in binary, just pull the plug.

valid8 is a thin, opinionated wrapper around go-playground/validator that solves a common pain point in API development: automatic, locale-aware validation error messages without manual translator wiring.

---

[!IMPORTANT] Quick heads-up: While a robot wrote these words (and all the comments in the code and the unit tests), the actual code, logic and design were 100% human-made. That's why you'll hate it more than the other validator libs out there.

Why valid8?

When building APIs with go-playground/validator, returning translated error messages requires loading and registering translators manually for every locale you want to support — and then selecting the right one at request time. This boilerplate multiplies fast.

valid8 abstracts that away:

• Pre-bundled translators for the most common locales (en, pt_BR, es, fr, de, ja, zh, zh_TW).
• Extended translation coverage — fills in tags that the original validator translations miss (e.g. required_if, alphanumspace, datetime, cron, jwt, and more).
• Custom tag support — register your own validation tags with translations in any locale using the same fluent API.
• API-friendly error output — a single ErrorsToMap() call converts validation errors into a map[string]string ready to be serialised as JSON.

---

Installation

go get github.com/audryus/valid8

---

Quick Start

package main

import (
    "encoding/json"
    "fmt"

    "github.com/audryus/valid8"
)

type CreateUserRequest struct {
    Name  string `validate:"required"`
    Email string `validate:"required,email"`
    Age   int    `validate:"required,gte=18"`
}

func main() {
    // Create a validator with Brazilian Portuguese support.
    v := valid8.New(valid8.WithLocales(valid8.PT_BR))

    req := CreateUserRequest{Name: ""}
    errs := v.Struct(req, valid8.PT_BR)

    // Convert to map and serialise — ideal for API responses.
    out, _ := json.MarshalIndent(valid8.ErrorsToMap(errs), "", "  ")
    fmt.Println(string(out))
    // {
    //   "createuserrequest.name":  "Name é um campo obrigatório",
    //   "createuserrequest.email": "Email é um campo obrigatório",
    //   "createuserrequest.age":   "Age é um campo obrigatório"
    // }
}

---

Supported Locales

Constant	Locale
EN	English
PT_BR	Portuguese (Brazil)
ES	Spanish
FR	French
DE	German
JA	Japanese
ZH	Chinese (Simplified)
ZHTW	Chinese (Traditional)

English (EN) is always registered and used as the fallback when a requested locale is not available.

Register specific locales

v := valid8.New(valid8.WithLocales(valid8.PT_BR, valid8.ES))

Register all locales at once

v := valid8.New(valid8.WithAllLocales())

---

API Reference

New(opts ...ConfigFunc) *Valid8

Creates a new Valid8 instance. English is always registered by default. Additional locales are loaded via ConfigFunc options.

(*Valid8) Struct(s any, language Locale) []ValidationErrors

Validates a struct and returns the errors translated into the requested language. Falls back to English if the locale is not registered.

ErrorsToMap(errors []ValidationErrors) map[string]string

Converts a slice of ValidationErrors into a flat map[string]string keyed by the lowercased field namespace (e.g. "user.address.city"). This is the recommended format for JSON API error responses.

WithLocales(locales ...Locale) ConfigFunc

Returns a ConfigFunc that registers the given locales (plus English) on the validator.

WithAllLocales() ConfigFunc

Returns a ConfigFunc that registers every bundled locale.

---

Using the Underlying Validator

The embedded *validator.Validate instance is publicly accessible, so you can register custom tags and translations without losing any valid8 features:

v := valid8.New(valid8.WithLocales(valid8.PT_BR))

// Register a custom validation tag using the standard go-playground API.
v.Validator.RegisterValidation("notexample", func(fl validator.FieldLevel) bool {
    return fl.Field().String() != "example"
})

---

Gin / Echo / Fiber Integration

Because Struct returns a plain []ValidationErrors and ErrorsToMap produces a map[string]string, integration with any HTTP framework is trivial:

// Gin example
func CreateUser(c *gin.Context) {
    var req CreateUserRequest
    c.ShouldBindJSON(&req)

    lang := valid8.Locale(c.GetHeader("Accept-Language"))
    if errs := v.Struct(req, lang); len(errs) > 0 {
        c.JSON(http.StatusUnprocessableEntity, gin.H{"errors": valid8.ErrorsToMap(errs)})
        return
    }
    // ...
}

---

[!NOTE] Final Warning: If you've made it this far, you've survived a README written mostly by an AI. Don't worry, the human owner vetted the structure and usage to make sure they're actually useful. Now go forth and validate like a pro!

No I didn't, stop lying.

License

MIT

Documentation

Index

• Variables
• func ErrorsToMap(errors []ValidationErrors) map[string]string
• func WithAllLocales() configFunc
• func WithLocales(locales ...Locale) configFunc
• type Locale
• type Translation
• type Valid8
  • func New(opts ...configFunc) *Valid8
  • func (v *Valid8) RegisterTranslation(translation Translation) error
  • func (v *Valid8) Struct(s any, language Locale) []ValidationErrors
• type ValidationErrors
  • func (v *ValidationErrors) Message() string
  • func (v *ValidationErrors) Namespace() string

Variables

var (
	// ErrTagMandatory is returned when a translation is registered without a tag.
	ErrTagMandatory = errors.New("Tag is mandatory")
	// ErrTextMandatory is returned when a translation is registered without text.
	ErrTextMandatory = errors.New("Text is mandatory")
	// ErrLocaleMandatory is returned when a translation is registered without a locale.
	ErrLocaleMandatory = errors.New("Locale is mandatory")
)

Functions

func ErrorsToMap

func ErrorsToMap(errors []ValidationErrors) map[string]string

ErrorsToMap converts a slice of ValidationErrors into a map where the key is the field namespace and the value is the human-readable error message.

func WithAllLocales

func WithAllLocales() configFunc

WithAllLocales configures the Valid8 instance to support all available locales.

func WithLocales

func WithLocales(locales ...Locale) configFunc

WithLocales configures the Valid8 instance to support a specific set of locales. English (EN) is always registered by default.

Types

type Locale

type Locale string

Locale represents a language identifier used for localized validation messages.

const (
	// EN represents the English locale.
	EN Locale = "en"
	// PT_BR represents the Brazilian Portuguese locale.
	PT_BR Locale = "pt_BR"
	// ES represents the Spanish locale.
	ES Locale = "es"
	// FR represents the French locale.
	FR Locale = "fr"
	// DE represents the German locale.
	DE Locale = "de"
	// JA represents the Japanese locale.
	JA Locale = "ja"
	// ZH represents the Chinese (Simplified) locale.
	ZH Locale = "zh"
	// ZHTW represents the Chinese (Traditional) locale.
	ZHTW Locale = "zh_TW"
)

type Translation

type Translation struct {
	// IgnoreFallback if true, prevents the translation from being registered for the default English (EN) locale
	// if the primary Locale is different.
	IgnoreFallback bool
	// Text is the localized error message template (e.g., "{0} is invalid").
	Text string
	// IgnoreOverride if true, prevents the translation from overriding an existing one for the same tag and locale.
	IgnoreOverride bool
	// Locale is the target language for this translation.
	Locale Locale
	// Tag is the validation tag identifier (e.g., "required", "email", "custom_tag").
	Tag string
	// TranslationFn is the function responsible for generating the localized error message.
	// This field is optional; if not provided, it defaults to an internal translation function
	// that retrieves the message from the universal-translator using the specified Tag.
	TranslationFn validator.TranslationFunc
}

Translation defines the configuration for a custom validation tag translation.

type Valid8

type Valid8 struct {
	// Validator is the underlying go-playground/validator instance used for validation.
	Validator *validator.Validate
	// contains filtered or unexported fields
}

Valid8 is the main structure for handling multi-language struct validation.

func New

func New(opts ...configFunc) *Valid8

New creates and initializes a new Valid8 instance with the provided configuration options.

func (*Valid8) RegisterTranslation

func (v *Valid8) RegisterTranslation(translation Translation) error

RegisterTranslation registers a custom translation for a specific locale. By default, it also registers the translation for the English (EN) locale as a fallback, unless IgnoreFallback is set to true. This ensures that the custom validation tag has a meaningful message even if the requested language is not available.

func (*Valid8) Struct

func (v *Valid8) Struct(s any, language Locale) []ValidationErrors

Struct validates the provided struct 's' using the specified 'language' for error messages. If the specified language is not registered, it defaults to English (EN).

type ValidationErrors

type ValidationErrors struct {
	validator.FieldError
	// contains filtered or unexported fields
}

ValidationErrors wraps a validator.FieldError and its corresponding translated message.

func (*ValidationErrors) Message

func (v *ValidationErrors) Message() string

Message returns the translated, human-readable error message.

func (*ValidationErrors) Namespace

func (v *ValidationErrors) Namespace() string

Namespace returns the field namespace (e.g., "User.Email") in lowercase.