From 72272ff90313211f3c05639fabd3d3ade09ae7c3 Mon Sep 17 00:00:00 2001 From: Onur Cinar Date: Sun, 29 Dec 2024 04:45:26 -0800 Subject: [PATCH] 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. --- v2/DOC.md | 4 ++++ v2/README.md | 49 ++++++++++++++++++++++++++++++++++++++++++ v2/check_error.go | 2 +- v2/check_error_test.go | 10 ++++----- v2/locales/DOC.md | 4 ++-- v2/locales/en_us.go | 4 ++-- v2/maker_test.go | 4 ++++ 7 files changed, 67 insertions(+), 10 deletions(-) diff --git a/v2/DOC.md b/v2/DOC.md index ceea0fe..f64c329 100644 --- 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 index 9faecb8..3b7f41d 100644 --- 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 index 139e72c..0f96876 100644 --- 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 index ec7dec3..c400490 100644 --- 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 index a512cd3..88718f0 100644 --- a/v2/locales/DOC.md +++ b/v2/locales/DOC.md @@ -29,10 +29,10 @@ const ( ## Variables -EnUsMessages is the map of en\-US messages. +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 index 774be83..c35c55b 100644 --- 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 index 428bd3b..fcc839c 100644 --- 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)