lingo

README

lingo

Very basic Golang library for i18n. There are others that do the job, but this is my take on the problem.

Features:

1. Storing messages in JSON files.
2. Support for nested declarations.
3. Detecting language based on Request headers.
4. Very simple to use.

Usage:

1. Import Lingo into your project

     import "github.com/kortem/lingo"
   

2. Create a dir to store translations, and write them in JSON files named [locale].json. For example:

     en_US.json
     sr_RS.json
     de.json
     ...
   

   You can write nested JSON too.

     {
       "main.title" : "CutleryPlus",
       "main.subtitle" : "Knives that put cut in cutlery.",
       "menu" : {
         "home" : "Home",
         "products": {
           "self": "Products",
           "forks" : "Forks",
           "knives" : "Knives",
           "spoons" : "Spoons"
         },
       }
     }
   

3. Initialize a Lingo like this:

     l := lingo.New("default_locale", "path/to/translations/dir")
   

4. Get bundle for specific locale via either string:

     t1 := l.TranslationsForLocale("en_US")
     t2 := l.TranslationsForLocale("de_DE")
   

   This way Lingo will return the bundle for specific locale, or default if given is not found. Alternatively (or primarily), you can get it with *http.Request:

     t := l.TranslationsForRequest(req)
   

   This way Lingo finds best suited locale via Accept-Language header, or if there is no match, returns default. Accept-Language header is set by the browser, so basically it will serve the language the user has set to his browser.

5. Once you get T instance just fire away!

     r1 := t1.Value("main.subtitle")
     // "Knives that put cut in cutlery."
     r1 := t2.Value("main.subtitle")
     // "Messer, die legte in Besteck geschnitten."
     r3 := t1.Value("menu.products.self")
     // "Products"
     r5 := t1.Value("error.404", req.URL.Path)
     // "Page index.html not found!"
   

Contributions:

I regard this little library as feature-complete, but if you have an idea on how to improve it, feel free to create issues. Also, pull requests are welcome. Enjoy!

Documentation

Index

• type L
  • func New(deflt, path string) *L
  • func (l *L) TranslationsForLocale(locale string) T
  • func (l *L) TranslationsForRequest(r *http.Request) T
• type Locale
  • func GetLocales(r *http.Request) []Locale
  • func GetPreferredLocale(r *http.Request) (*Locale, error)
  • func ParseLocale(locale string) Locale
  • func (l *Locale) Name() string
• type T
  • func (t T) Value(key string, args ...string) string

Types

type L

type L struct {
	// contains filtered or unexported fields
}

L represents Lingo bundle, containing map of all Ts by locale, as well as default locale and list of supported locales

func New

func New(deflt, path string) *L

New creates the Lingo bundle. Params: Default locale, to be used when requested locale is not found. Path, absolute or relative path to a folder where translation .json files are kept

func (*L) TranslationsForLocale

func (l *L) TranslationsForLocale(locale string) T

TranslationsForLocale will get the T for specific locale. If no locale is found, returns default T

func (*L) TranslationsForRequest

func (l *L) TranslationsForRequest(r *http.Request) T

TranslationsForRequest will get the best matched T for given Request. If no T is found, returns default T

type Locale

type Locale struct {
	Lang, Country string
	Qual          float64
}

Locale is locale value from the Accept-Language header in request

func GetLocales

func GetLocales(r *http.Request) []Locale

GetLocales returns supported locales for the given requet

func GetPreferredLocale

func GetPreferredLocale(r *http.Request) (*Locale, error)

GetPreferredLocale return preferred locale for the given reuqest returns error if there is no preferred locale

func ParseLocale

func ParseLocale(locale string) Locale

ParseLocale creates a Locale from a locale string

func (*Locale) Name

func (l *Locale) Name() string

Name returns the locale value in 'lang' or 'lang_country' format eg: de_DE, en_US, gb

type T

type T struct {
	// contains filtered or unexported fields
}

T represents translations map for specific locale

func (T) Value

func (t T) Value(key string, args ...string) string

Value traverses the translations map and finds translation for given key. If no translation is found, returns value of given key.