Added examples for the localized error messages. (#156)

# Describe Request Added examples for the localized error messages section of the documentation. # Change Type Documentation improvement.
cinar · Dec 29, 2024 · 72272ff · 72272ff
1 parent 2c3a57b
commit 72272ff
Show file tree

Hide file tree

Showing 7 changed files with 67 additions and 10 deletions.
diff --git a/v2/DOC.md b/v2/DOC.md
@@ -1193,10 +1193,14 @@ import (
 	"fmt"
 	"reflect"
 
+	"github.com/cinar/checker/v2/locales"
+
 	v2 "github.com/cinar/checker/v2"
 )
 
 func main() {
+	locales.EnUSMessages["NOT_FRUIT"] = "Not a fruit name."
+
 	v2.RegisterMaker("is-fruit", func(params string) v2.CheckFunc[reflect.Value] {
 		return func(value reflect.Value) (reflect.Value, error) {
 			stringValue := value.Interface().(string)

diff --git a/v2/README.md b/v2/README.md
@@ -176,12 +176,61 @@ In this example:
 
 When validation fails, Checker returns an error. By default, the [Error()](DOC.md#CheckError.Error) function provides a human-readable error message in `en-US` locale.
 
+```golang
+_, err := checker.IsEmail("abcd")
+if err != nil {
+	fmt.Println(err)
+	// Output: Not a valid email address.
+}
+```
+
 To get error messages in other languages, use the [ErrorWithLocale()](DOC.md#CheckError.ErrorWithLocale) function. By default, only `en-US` is registered. You can register additional languages by calling [RegisterLocale](DOC.md#RegisterLocale).
 
+```golang
+// Register de-DE localized error messages.
+checker.RegisterLocale(locales.DeDE, locales.DeDEMessages)
+
+_, err := checker.IsEmail("abcd")
+if err != nil {
+	fmt.Println(err)
+	// Output: Keine gültige E-Mail-Adresse.
+}
+```
+
 You can also customize existing error messages or add new ones to `locales.EnUSMessages` and other locale maps.
 
+```golang
+// Register the en-US localized error message for the custom NOT_FRUIT error code.
+locales.EnUSMessages["NOT_FRUIT"] = "Not a fruit name."
+
+errors, valid := v2.CheckStruct(item)
+if !valid {
+	fmt.Println(errors)
+	// Output: map[Name:Not a fruit name.]
+}
+```
+
 Error messages are generated using Golang template functions, allowing them to include variables.
 
+```golang
+// Custrom checker error containing the item name.
+err := NewCheckErrorWithData(
+	"NOT_FRUIT",
+	map[string]interface{}{
+		"name": name,
+	},
+)
+
+// Register the en-US localized error message for the custom NOT_FRUIT error code.
+locales.EnUSMessages["NOT_FRUIT"] = "Name {{ .name }} is not a fruit name."
+
+errors, valid := v2.CheckStruct(item)
+if !valid {
+	fmt.Println(errors)
+	// Output: map[Name:Name abcd is not a fruit name.]
+}
+```
+
 # Contributing to the Project
 
 Anyone can contribute to Checkers library. Please make sure to read our [Contributor Covenant Code of Conduct](./CODE_OF_CONDUCT.md) guide first. Follow the [How to Contribute to Checker](./CONTRIBUTING.md) to contribute.

diff --git a/v2/check_error.go b/v2/check_error.go
@@ -28,7 +28,7 @@ const (
 
 // errorMessages is the map of localized error messages.
 var errorMessages = map[string]map[string]string{
-	locales.EnUS: locales.EnUsMessages,
+	locales.EnUS: locales.EnUSMessages,
 }
 
 // NewCheckError creates a new check error with the given code.

diff --git a/v2/check_error_test.go b/v2/check_error_test.go
@@ -27,7 +27,7 @@ func TestCheckErrorWithLocalizedCode(t *testing.T) {
 	code := "TEST"
 	message := "Test message"
 
-	locales.EnUsMessages[code] = message
+	locales.EnUSMessages[code] = message
 
 	err := v2.NewCheckError(code)
 
@@ -40,7 +40,7 @@ func TestCheckErrorWithDefaultLocalizedCode(t *testing.T) {
 	code := "TEST"
 	message := "Test message"
 
-	locales.EnUsMessages[code] = message
+	locales.EnUSMessages[code] = message
 
 	err := v2.NewCheckError(code)
 
@@ -53,7 +53,7 @@ func TestCheckErrorWithDataAndLocalizedCode(t *testing.T) {
 	code := "TEST"
 	message := "Test message {{.Name}}"
 
-	locales.EnUsMessages[code] = message
+	locales.EnUSMessages[code] = message
 
 	err := v2.NewCheckErrorWithData(code, map[string]interface{}{
 		"Name": "Onur",
@@ -70,7 +70,7 @@ func TestCheckErrorWithLocalizedCodeInvalidTemplate(t *testing.T) {
 	code := "TEST"
 	message := "Test message {{}"
 
-	locales.EnUsMessages[code] = message
+	locales.EnUSMessages[code] = message
 
 	err := v2.NewCheckError(code)
 
@@ -83,7 +83,7 @@ func TestCheckErrorWithLocalizedCodeInvalidExecute(t *testing.T) {
 	code := "TEST"
 	message := "{{ len .Name}}"
 
-	locales.EnUsMessages[code] = message
+	locales.EnUSMessages[code] = message
 
 	err := v2.NewCheckError(code)
 

diff --git a/v2/locales/DOC.md b/v2/locales/DOC.md
@@ -29,10 +29,10 @@ const (
 
 ## Variables
 
-<a name="EnUsMessages"></a>EnUsMessages is the map of en\-US messages.
+<a name="EnUSMessages"></a>EnUSMessages is the map of en\-US messages.
 
 ```go
-var EnUsMessages = map[string]string{
+var EnUSMessages = map[string]string{
     "NOT_ALPHANUMERIC": "Not an alphanumeric string.",
     "NOT_ASCII":        "Can only contain ASCII characters.",
     "NOT_CIDR":         "Not a valid CIDR notation.",

diff --git a/v2/locales/en_us.go b/v2/locales/en_us.go
@@ -5,8 +5,8 @@ const (
 	EnUS = "en-US"
 )
 
-// EnUsMessages is the map of en-US messages.
-var EnUsMessages = map[string]string{
+// EnUSMessages is the map of en-US messages.
+var EnUSMessages = map[string]string{
 	"NOT_ALPHANUMERIC": "Not an alphanumeric string.",
 	"NOT_ASCII":        "Can only contain ASCII characters.",
 	"NOT_CIDR":         "Not a valid CIDR notation.",

diff --git a/v2/maker_test.go b/v2/maker_test.go
@@ -10,6 +10,8 @@ import (
 	"reflect"
 	"testing"
 
+	"github.com/cinar/checker/v2/locales"
+
 	v2 "github.com/cinar/checker/v2"
 )
 
@@ -28,6 +30,8 @@ func TestMakeCheckersUnknown(t *testing.T) {
 }
 
 func ExampleRegisterMaker() {
+	locales.EnUSMessages["NOT_FRUIT"] = "Not a fruit name."
+
 	v2.RegisterMaker("is-fruit", func(params string) v2.CheckFunc[reflect.Value] {
 		return func(value reflect.Value) (reflect.Value, error) {
 			stringValue := value.Interface().(string)