lingo

README

lingo-toml

Very basic Golang library for i18n.

The original project was by @kortemy, and uses JSON. A fork by jdkeke142 changed the input to TOML. This fork abstracts the file system away, allowing the use of (for example) embedded assets, or assets that don't live on the local disk. It was put together around broccoli, with which it's been tested.

Features:

1. Storing messages in TOML 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/xxxserxxx/lingo"
   

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

     en_US.toml
     sr_RS.toml
     de.toml
     ...
   

   You can write nested TOML too.

     title = "CutleryPlus"
     subtitle = "Knives that put cut in cutlery."
   
       [menu]
       home = "Home"
   
         [menu.products]
         self = "Products"
         forks = "Forks"
         knives = "Knives"
         spoons = "Spoons"
   

3. Initialize a Lingo like this:

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

   This is where you would pass in a lingo.FileSystem if you want lingo to read from something other than the disk. Passing in nil is the same as calling:

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

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!"
   

Behaviors

• Lingo will return the default locale if it can't find a requested locale.

• Lingo will return the default locale's text if it can't find a translation for the key in the requested locale.

• Lingo will return the requested key if it can't find either the requested or the default text.

• Text values can have positional tags, e.g. {0}, {1}. These will be replaced by any varargs supplied to Value. E.g.:

  thing="Hey there, {1}, how is {0}?"
  

  and

  res := t1.Value("thing", "your dog", "person")
  

  will produce

  Hey there, person, how is your dog
  

• Locales must match the file names. E.g., en_US must be in a file called en_US.toml, not en_us.toml.

• Files in the translation directory that do not end in .toml are ignored.

Contributions

This was forked to support another project; I'll accept PRs and will fix bugs, but am unlikely to add features.

Documentation

Index

• type Lingo
  • func New(deflt, path string, root fs.FS) (*Lingo, error)
  • func (l *Lingo) TranslationsForLocale(locale string) Translations
  • func (l *Lingo) TranslationsForRequest(r *http.Request) Translations
• 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 Translations
  • func (t Translations) Value(key string, args ...string) string

Types

type Lingo

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

Lingo is a translation bundle of all translations by locale, as well as default locale and list of supported locales

func New

func New(deflt, path string, root fs.FS) (*Lingo, error)

New creates the Lingo bundle. `deflt` is the default locale, which is used when the requested locale is not found, and when translations are not found in the requested locale. `path` is the absolute or relative path to the folder of TOML translations. `fs` is either a FileSystem or null, used to locate the path and translation files.

func (*Lingo) TranslationsForLocale

func (l *Lingo) TranslationsForLocale(locale string) Translations

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

func (*Lingo) TranslationsForRequest

func (l *Lingo) TranslationsForRequest(r *http.Request) Translations

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 Translations

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

Translations represents translations map for specific locale

func (Translations) Value

func (t Translations) 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.