go-localize

Simple and easy to use i18n (Internationalization and localization) engine written in Go, used for translating locale strings. Use with go generate or on the CLI. Currently supports JSON, YAML, TOML and CSV translation files

Why another i18n library?

This package aims to be as simple and easy to use as possible. It also takes inspiration from popular localization libraries/packages in other languages - so makes it easier to reason about coming from other languages and frameworks.

Usage

Go generate

The suggested way to use go-localize is to use go generate. For example, take the following directory structure:

goapp
└── localizations_src
    ├── en
    │   └── messages.yaml
    └── es
        ├── customer
        │   └── messages.json
        └── messages.json

Example of JSON translation file:

{
  "hello": "Hola",
  "how_are_you": "¿Cómo estás?",
  "whats_your_name": "¿Cuál es tu nombre?",
  "hello_my_name_is": "Hola, mi nombre es {{.name}}"
}

Example of YAML translation file:

hello: hello
how_are_you: How are you?
whats_your_name: "What's your name?"
hello_my_name_is: Hello my name is {{.name}}
hello_firstname_lastname: Hello {{.firstname}} {{.lastname}}

Example of CSV translation file:

hello, hello
how_are_you, How are you?

Example of TOML translation file:

hello = "hello"
how_are_you = "How are you?"

To then generate the localization package, add the following to your main.go or another one of your .go files:

//go:generate go-localize -input localizations_src -output localizations

If you want to include UTC timestamp for the output generation, add -timestamp flag.

Now you'll be able to use the localization like so:

l := localizations.New("en", "es")

println(l.Get("messages.how_are_you")) // How are you?

println(l.GetWithLocale("es", "messages.hello_my_name_is", &localizations.Replacements{"name":"steve"})) // "Hola, mi nombre es steve"

With en being the locale and es being the fallback. The localization keys are worked out using folder structure, eg:

en/customer/messages.json with the contents being:

{
  "hello": "hello customer!"
}

You'll be able to access this using the key: customer.messages.hello.

Suggestions

It is suggested to instead of using hardcoded locale keys i.e. en to use the language keys included in key, i.e: language.BritishEnglish.String() which is en-GB

Replacements

Take this replacement string for example:

hello_firstname_lastname: Hello {{.firstname}} {{.lastname}}

To then replace firstname and the lastname variable, you can use something like this:

l := localizations.New("en", "es")
println(l.Get("hello_firstname_lastname", &localizations.Replacements{"firstname": "steve", "lastname": "steve"}))

You can also append numerous replacements if you have them like so:

println(l.Get("hello_firstname_lastname", &localizations.Replacements{"firstname": "steve"}, &localizations.Replacements{"lastname": "steve"}))

Locale defining and localization fallbacks

You can define the locale and fallbacks using:

l := localizations.New("en", "es")

Where en is the locale and es is the fallback. If no translation key-value is found then the key will be returned. For example

println(l.Get("key_doesnt_exist")) //"key_doesnt_exist" will be printed

Translation file support

We currently support JSON, YAML, TOML and CSV translation files. Please suggest missing file type using issues or pull requests.

CLI

Instead of using go generate you can just generate the localizations manually using go-localize:

Usage of go-localize:
  -input string
        input localizations folder
  -output string
        where to output the generated package
  -timestamp
        write creation time in generated file