docs: enhance code documentation for ginI18n implementation

- Add detailed comments for the `ginI18nImpl` struct and its methods
- Add detailed comments for the `GinI18n` interface and its methods
- Add detailed comments for the `GetLngHandler` and `Option` types

Signed-off-by: appleboy <[email protected]>

ginI18n.go

@@ -1,3 +1,24 @@
+// ginI18nImpl is an implementation of the GinI18n interface, providing
+// localization support for Gin applications. It uses the go-i18n library
+// to manage and retrieve localized messages.
+//
+// Fields:
+// - bundle: The i18n.Bundle containing the localization messages.
+// - localizerByLng: A map of language tags to their corresponding localizers.
+// - defaultLanguage: The default language tag to use for localization.
+// - getLngHandler: A handler function to retrieve the language tag from the Gin context.
+//
+// Methods:
+// - GetMessage: Retrieves a localized message based on the provided context and parameter.
+// - MustGetMessage: Retrieves a localized message and returns an empty string if retrieval fails.
+// - SetBundle: Sets the i18n.Bundle configuration.
+// - SetGetLngHandler: Sets the handler function to retrieve the language tag from the Gin context.
+// - loadMessageFiles: Loads all localization files into the bundle.
+// - loadMessageFile: Loads a single localization file into the bundle.
+// - setLocalizerByLng: Sets the localizers for each accepted language.
+// - newLocalizer: Creates a new localizer for a given language.
+// - getLocalizerByLng: Retrieves the localizer for a given language.
+// - getLocalizeConfig: Converts the parameter into an i18n.LocalizeConfig.
 package i18n
 
 import (
@@ -10,6 +31,8 @@ import (
 	"golang.org/x/text/language"
 )
 
+// GinI18n is an interface that defines methods for internationalization (i18n) in a Gin web framework context.
+// It provides methods to get localized messages and configure the i18n bundle and language handler.
 var _ GinI18n = (*ginI18nImpl)(nil)
 
 type ginI18nImpl struct {
@@ -19,7 +42,16 @@ type ginI18nImpl struct {
 	getLngHandler   GetLngHandler
 }
 
-// getMessage get localize message by lng and messageID
+// GetMessage retrieves a localized message based on the provided context and parameter.
+// If the message cannot be retrieved, it returns an empty string.
+//
+// Parameters:
+//   - ctx: The Gin context from which to retrieve the message.
+//   - param: The parameter used to fetch the localized message.
+//
+// Returns:
+//   - string: The localized message or an empty string if retrieval fails.
+//   - error: An error if the message retrieval fails.
 func (i *ginI18nImpl) GetMessage(ctx *gin.Context, param interface{}) (string, error) {
 	lng := i.getLngHandler(ctx, i.defaultLanguage.String())
 	localizer := i.getLocalizerByLng(lng)
@@ -37,12 +69,27 @@ func (i *ginI18nImpl) GetMessage(ctx *gin.Context, param interface{}) (string, e
 	return message, nil
 }
 
-// mustGetMessage ...
+// MustGetMessage retrieves a localized message based on the provided context and parameter.
+// If the message cannot be retrieved, it returns an empty string.
+// This method panics if the message retrieval fails.
+//
+// Parameters:
+//   - ctx: The Gin context from which to retrieve the message.
+//   - param: The parameter used to fetch the localized message.
+//
+// Returns:
+//   - string: The localized message or an empty string if retrieval fails.
 func (i *ginI18nImpl) MustGetMessage(ctx *gin.Context, param interface{}) string {
 	message, _ := i.GetMessage(ctx, param)
 	return message
 }
 
+// SetBundle initializes the i18n bundle with the provided configuration.
+// It sets the default language, registers the unmarshal function for the bundle files,
+// loads the message files, and sets the localizer based on the accepted languages.
+//
+// Parameters:
+//   - cfg: A pointer to a BundleCfg struct that contains the configuration for the bundle.
 func (i *ginI18nImpl) SetBundle(cfg *BundleCfg) {
 	bundle := i18n.NewBundle(cfg.DefaultLanguage)
 	bundle.RegisterUnmarshalFunc(cfg.FormatBundleFile, cfg.UnmarshalFunc)
@@ -54,6 +101,12 @@ func (i *ginI18nImpl) SetBundle(cfg *BundleCfg) {
 	i.setLocalizerByLng(cfg.AcceptLanguage)
 }
 
+// SetGetLngHandler sets the handler function that will be used to get the language.
+// The handler should be a function that implements the GetLngHandler interface.
+//
+// Parameters:
+//
+//	handler - a function that implements the GetLngHandler interface
 func (i *ginI18nImpl) SetGetLngHandler(handler GetLngHandler) {
 	i.getLngHandler = handler
 }

interface.go

@@ -4,10 +4,20 @@ import (
 	"github.com/gin-gonic/gin"
 )
 
-// GinI18n ...
+// GinI18n is an interface that defines methods for internationalization (i18n) in a Gin web framework context.
+// It provides methods to get localized messages and configure the i18n bundle and language handler.
 type GinI18n interface {
+	// GetMessage retrieves a localized message based on the provided context and parameter.
+	// It returns the localized message as a string and an error if the message could not be retrieved.
 	GetMessage(context *gin.Context, param interface{}) (string, error)
+
+	// MustGetMessage retrieves a localized message based on the provided context and parameter.
+	// It returns the localized message as a string and panics if the message could not be retrieved.
 	MustGetMessage(context *gin.Context, param interface{}) string
+
+	// SetBundle sets the i18n bundle configuration.
 	SetBundle(cfg *BundleCfg)
+
+	// SetGetLngHandler sets the handler function to determine the language from the context.
 	SetGetLngHandler(handler GetLngHandler)
 }

type.go

@@ -3,9 +3,10 @@ package i18n
 import "github.com/gin-gonic/gin"
 
 type (
-	// GetLngHandler ...
+	// Option is a function type that takes a GinI18n instance and applies a configuration to it.
+	// It is used to customize the behavior of the GinI18n middleware.
 	GetLngHandler = func(context *gin.Context, defaultLng string) string
 
-	// Option ...
+	// Option is a function type that takes a GinI18n instance and applies a configuration to it.
 	Option func(GinI18n)
 )