README
¶
go.localization
The go.localization package provides a simple and convenient way to retrieve strings
in various languages, allowing you to easily build multilingual applications.
Key features
- Support strings with named variable.
- Support
jsonandyamltranslation files.
Installation
to install go.localization package, run the following command
go get -u github.com/behzadsh/go.localization
Defining Translation Strings
The go.localization package, loads the translations from json or yaml files, which by default should be
stored in {ProjectRoot}/resources/lang directory. The path to translation files are configurable, we discuss it later.
No matter you choose json or yaml the structure of the translation file must be like the following example.
The yaml file:
key_string:
locale1: "translation in locale1"
locale2: "translation in locale2"
The json file:
{
"key_string": {
"locale1": "translation in locale1"
"locale2": "translation in locale2"
}
}
conventions
- It is recommended to use
snake_casenames for the translation file name and the translation key. - It is recommended to use 2 letter abbreviation for locales, e.g. ISO 639-1.
Retrieving Translation Strings
For retrieving translation strings, you need to pass the translation key and the language to the translation function.
The translation key is consist of the translation file name and the translation key concatenated by a dot.
For example "user.not_found" as a translation key, means that the translation is located in a file named
user under the key not_found. With this in mind lets continue.
Using default configuration and helper functions
The easiest way to use the go.localization package is that you store your translation files in default path
(as mentioned above in the {ProjectRoot}/resources/lang). In this way, you can simply translate the keys like this:
main.go:
package main
import (
"fmt"
lang "github.com/behzadsh/go.localization"
)
func main() {
lang.Init()
// Simple translation
fmt.Println(lang.Trans("user.not_found")) // User not found!
fmt.Println(lang.Trans("errors.invalid_payload")) // The payload is invalid!
fmt.Println(lang.TransBy("zh", "user.not_found")) // 找不到用户!
// Translation with parameter
fmt.Println(lang.Trans("validation.required", map[string]string{"field": "email"})) // The field 'email' is required.
fmt.Println(lang.TransBy("zh", "validation.required", map[string]string{"field": "email"})) // 字段 'email' 是必需的。
}
./resources/lang/user.yaml:
not_found:
en: "User not found!"
zh: "找不到用户!"
./resources/lang/errors.yaml:
invalid_payload:
en: "The payload is invalid!"
zh: "负载无效!"
./resources/lang/validations.yaml:
required:
en: "The field ':field:' is required."
zh: "字段 ':field:' 是必需的。"
Using the translator struct directly
package main
import (
"fmt"
"log"
lang "github.com/behzadsh/go.localization"
)
func main() {
tr, err := lang.NewTranslator(lang.DefaultConfigs())
if err != nil {
log.Fatal(err)
}
// Simple translation
fmt.Println(tr.Translate("user.not_found")) // User not found!
fmt.Println(tr.Translate("errors.invalid_payload")) // The payload is invalid!
fmt.Println(tr.TranslateBy("zh", "user.not_found")) // 找不到用户!
// Translation with parameter
fmt.Println(tr.Translate("validation.required", map[string]string{"field": "email"})) // The field 'email' is required.
fmt.Println(tr.TranslateBy("zh", "validation.required", map[string]string{"field": "email"})) // 字段 'email' 是必需的。
}
Configuration
You can configure the following options:
- Translation files path: The path to where the translation files are stored.
- The default language: The default language used by functions like
TransandTranslate - The fallback language: The language used when the no translation found for default or given language.
If you rather use helper function, you can customize these options by these functions before calling Init()
package main
import (
lang "github.com/behzadsh/go.localization"
)
func main() {
lang.SetDefaultLocale("zh")
lang.SetFallbackLocale("fr")
lang.SetTranslationFilesPath("relative/path/to/somewhere/else")
lang.Init()
// ...
}
Or if you want to use the translator struct directly, you can pass your custom configuration to the constructor.
package main
import (
"log"
lang "github.com/behzadsh/go.localization"
)
func main() {
tr, err := lang.NewTranslator(lang.Config{
TranslationPath: "relative/path/to/somewhere/else",
DefaultLocale: "zh",
FallbackLocale: "fr",
})
if err != nil {
log.Fatal(err)
}
// ...
}
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func SetDefaultLocale ¶
func SetDefaultLocale(locale string)
SetDefaultLocale set translation default locale.
func SetFallbackLocale ¶
func SetFallbackLocale(locales string)
SetFallbackLocale set translation fallback locale.
func SetTranslationFilesPath ¶
func SetTranslationFilesPath(p string)
SetTranslationFilesPath set translation files path.
Types ¶
type Config ¶
type Config struct {
// Path to the where translations files are stored.
TranslationPath string
// The locale used for translation by default.
DefaultLocale string
// The fallback locale used when no translation found for default locale.
FallbackLocale string
}
Config is a config struct for configuring the Translator.
func DefaultConfigs ¶
func DefaultConfigs() Config
DefaultConfigs creates a new translation config instance with default config values.
type Translator ¶
type Translator struct {
// contains filtered or unexported fields
}
Translator is a tool to translate the translation key based on localization settings.
func NewTranslator ¶
func NewTranslator(cfg Config) (*Translator, error)
NewTranslator instantiate a new instance of Translator with given config.
func (*Translator) Translate ¶
func (t *Translator) Translate(key string, params ...map[string]string) string
Translate translates the given key using optional params with default locale.
func (*Translator) TranslateBy ¶
func (t *Translator) TranslateBy(locale, key string, params ...map[string]string) string
TranslateBy translate the given key using optional params with given locale.
Source Files