ut

README

universal-translator

 [](https://semaphoreci.com/joeybloggs/universal-translator) [](https://coveralls.io/github/go-playground/universal-translator) [](https://goreportcard.com/report/github.com/go-playground/universal-translator) [](https://godoc.org/github.com/go-playground/universal-translator)  [](https://gitter.im/go-playground/universal-translator?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)

Universal Translator is an i18n Translator for Go/Golang using CLDR data + pluralization rules

Why another i18n library?

Because none of the plural rules seem to be correct out there, including the previous implimentation of this package, so I took it upon myself to create locales for everyone to use; this package is a thin wrapper around locales in order to store and translate text for use in your applications.

Features

• Rules generated from the latest CLDR data, v29
• Contains Cardinal, Ordinal and Range Plural Rules
• Contains Month, Weekday and Timezone translations built in
• Contains Date & Time formatting functions
• Contains Number, Currency, Accounting and Percent formatting functions
• Supports the "Gregorian" calendar only ( my time isn't unlimited, had to draw the line somewhere )
• Support loading translations from files
• Exporting translations to file, mainly for getting them professionally translated
• Code Generation for translation files -> Go code.. i.e. after it has been professionally translated
• Tests for all languages, I need help with this, please see here

Installation

Use go get

go get github.com/go-playground/universal-translator

Usage

package main

import (
	"fmt"

	"github.com/go-playground/locales"
	"github.com/go-playground/locales/en"
	"github.com/go-playground/locales/en_CA"
	"github.com/go-playground/locales/fr"
	"github.com/go-playground/locales/nl"
	"github.com/go-playground/universal-translator"
)

// only one instance as translators within are shared + goroutine safe
var universalTraslator *ut.UniversalTranslator

func main() {

	// NOTE: this example is omitting allot of error checking for brevity
	e := en.New()
	universalTraslator = ut.New(e, e, en_CA.New(), nl.New(), fr.New())

	en := universalTraslator.GetTranslator("en")

	// generally used after parsing an http 'Accept-Language' header
	// and this will try to find a matching locale you support or
	// fallback locale.
	// en, _ := ut.FindTranslator([]string{"en", "en_CA", "nl"})

	// this will help
	fmt.Println("Cardinal Plural Rules:", en.PluralsCardinal())
	fmt.Println("Ordinal Plural Rules:", en.PluralsOrdinal())
	fmt.Println("Range Plural Rules:", en.PluralsRange())

	// add basic language only translations
	// last param indicates if it's ok to override the translation if one already exists
	en.Add("welcome", "Welcome {0} to our test", false)

	// add language translations dependant on cardinal plural rules
	en.AddCardinal("days", "You have {0} day left to register", locales.PluralRuleOne, false)
	en.AddCardinal("days", "You have {0} days left to register", locales.PluralRuleOther, false)

	// add language translations dependant on ordinal plural rules
	en.AddOrdinal("day-of-month", "{0}st", locales.PluralRuleOne, false)
	en.AddOrdinal("day-of-month", "{0}nd", locales.PluralRuleTwo, false)
	en.AddOrdinal("day-of-month", "{0}rd", locales.PluralRuleFew, false)
	en.AddOrdinal("day-of-month", "{0}th", locales.PluralRuleOther, false)

	// add language translations dependant on range plural rules
	// NOTE: only one plural rule for range in 'en' locale
	en.AddRange("between", "It's {0}-{1} days away", locales.PluralRuleOther, false)

	// now lets use the translations we just added, in the same order we added them

	fmt.Println(en.T("welcome", "Joeybloggs"))

	fmt.Println(en.C("days", 1, 0, string(en.FmtNumber(1, 0)))) // you'd normally have variables defined for 1 and 0
	fmt.Println(en.C("days", 2, 0, string(en.FmtNumber(2, 0))))
	fmt.Println(en.C("days", 10456.25, 2, string(en.FmtNumber(10456.25, 2))))

	fmt.Println(en.O("day-of-month", 1, 0, string(en.FmtNumber(1, 0))))
	fmt.Println(en.O("day-of-month", 2, 0, string(en.FmtNumber(2, 0))))
	fmt.Println(en.O("day-of-month", 3, 0, string(en.FmtNumber(3, 0))))
	fmt.Println(en.O("day-of-month", 4, 0, string(en.FmtNumber(4, 0))))
	fmt.Println(en.O("day-of-month", 10456.25, 0, string(en.FmtNumber(10456.25, 0))))

	fmt.Println(en.R("between", 0, 0, 1, 0, string(en.FmtNumber(0, 0)), string(en.FmtNumber(1, 0))))
	fmt.Println(en.R("between", 1, 0, 2, 0, string(en.FmtNumber(1, 0)), string(en.FmtNumber(2, 0))))
	fmt.Println(en.R("between", 1, 0, 100, 0, string(en.FmtNumber(1, 0)), string(en.FmtNumber(100, 0))))
}

Help With Tests

To anyone interesting in helping or contributing, I sure could use some help creating tests for each language. Please see issue here for details.

Documentation

Index

• Variables
• type ErrCardinalTranslation
  • func (e *ErrCardinalTranslation) Error() string
• type ErrConflictingTranslation
  • func (e *ErrConflictingTranslation) Error() string
• type ErrExistingTranslator
  • func (e *ErrExistingTranslator) Error() string
• type ErrMissingPluralTranslation
  • func (e *ErrMissingPluralTranslation) Error() string
• type ErrOrdinalTranslation
  • func (e *ErrOrdinalTranslation) Error() string
• type ErrRangeTranslation
  • func (e *ErrRangeTranslation) Error() string
• type Translator
• type UniversalTranslator
  • func New(fallback locales.Translator, supportedLocales ...locales.Translator) *UniversalTranslator
  • func (t *UniversalTranslator) AddTranslator(translator locales.Translator, override bool) error
  • func (t *UniversalTranslator) FindTranslator(locales ...string) (trans Translator)
  • func (t *UniversalTranslator) GetFallback() Translator
  • func (t *UniversalTranslator) GetTranslator(locale string) Translator

Variables

var (
	// ErrUnknowTranslation indicates the translation could not be found
	ErrUnknowTranslation = errors.New("Unknown Translation")
)

Types

type ErrCardinalTranslation

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

ErrCardinalTranslation is the error representing a cardinal translation error

func (*ErrCardinalTranslation) Error

func (e *ErrCardinalTranslation) Error() string

Error returns ErrCardinalTranslation's internal error text

type ErrConflictingTranslation

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

ErrConflictingTranslation is the error representing a conflicting translation

func (*ErrConflictingTranslation) Error

func (e *ErrConflictingTranslation) Error() string

Error returns ErrConflictingTranslation's internal error text

type ErrExistingTranslator

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

ErrExistingTranslator is the error representing a conflicting translator

func (*ErrExistingTranslator) Error

func (e *ErrExistingTranslator) Error() string

Error returns ErrExistingTranslator's internal error text

type ErrMissingPluralTranslation

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

ErrMissingPluralTranslation is the error signifying a missing translation given the locales plural rules.

func (*ErrMissingPluralTranslation) Error

func (e *ErrMissingPluralTranslation) Error() string

Error returns ErrMissingPluralTranslation's internal error text

type ErrOrdinalTranslation

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

ErrOrdinalTranslation is the error representing an ordinal translation error

func (*ErrOrdinalTranslation) Error

func (e *ErrOrdinalTranslation) Error() string

Error returns ErrOrdinalTranslation's internal error text

type ErrRangeTranslation

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

ErrRangeTranslation is the error representing a range translation error

func (*ErrRangeTranslation) Error

func (e *ErrRangeTranslation) Error() string

Error returns ErrRangeTranslation's internal error text

type Translator

type Translator interface {
	locales.Translator

	// adds a normal translation for a particular language/locale
	// {#} is the only replacement type accepted and are add infintium
	// eg. one: '{0} day left' other: '{0} days left'
	Add(key interface{}, text string, override bool) error

	// adds a cardinal plural translation for a particular language/locale
	// {0} is the only replacement type accepted and only one variable is accepted as
	// multiple cannot be used for a plural rule determination, unless it is a range;
	// see AddRange below.
	// eg. in locale 'en' one: '{0} day left' other: '{0} days left'
	AddCardinal(key interface{}, text string, rule locales.PluralRule, override bool) error

	// adds an ordinal plural translation for a particular language/locale
	// {0} is the only replacement type accepted and only one variable is accepted as
	// multiple cannot be used for a plural rule determination, unless it is a range;
	// see AddRange below.
	// eg. in locale 'en' one: '{0}st day of spring' other: '{0}nd day of spring'
	// - 1st, 2nd, 3rd...
	AddOrdinal(key interface{}, text string, rule locales.PluralRule, override bool) error

	// adds a range plural translation for a particular language/locale
	// {0} and {1} are the only replacement types accepted and only these are accepted.
	// eg. in locale 'nl' one: '{0}-{1} day left' other: '{0}-{1} days left'
	AddRange(key interface{}, text string, rule locales.PluralRule, override bool) error

	// creates the translation for the locale given the 'key' and params passed in
	T(key interface{}, params ...string) (string, error)

	// creates the cardinal translation for the locale given the 'key', 'num' and 'digit' arguments
	//  and param passed in
	C(key interface{}, num float64, digits uint64, param string) (string, error)

	// creates the ordinal translation for the locale given the 'key', 'num' and 'digit' arguments
	// and param passed in
	O(key interface{}, num float64, digits uint64, param string) (string, error)

	//  creates the range translation for the locale given the 'key', 'num1', 'digit1', 'num2' and
	//  'digit2' arguments and 'param1' and 'param2' passed in
	R(key interface{}, num1 float64, digits1 uint64, num2 float64, digits2 uint64, param1, param2 string) (string, error)

	// VerifyTranslations checks to ensures that no plural rules have been
	// missed within the translations.
	VerifyTranslations() error
}

Translator is universal translators translator instance which is a thin wrapper around locales.Translator instance providing some extra functionality

type UniversalTranslator

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

UniversalTranslator holds all locale & translation data

func New

func New(fallback locales.Translator, supportedLocales ...locales.Translator) *UniversalTranslator

New returns a new UniversalTranslator instance set with the fallback locale and locales it should support

func (*UniversalTranslator) AddTranslator

func (t *UniversalTranslator) AddTranslator(translator locales.Translator, override bool) error

AddTranslator adds the supplied translator, if it already exists the override param will be checked and if false an error will be returned, otherwise the translator will be overridden; if the fallback matches the supplied translator it will be overridden as well NOTE: this is normally only used when translator is embedded within a library

func (*UniversalTranslator) FindTranslator

func (t *UniversalTranslator) FindTranslator(locales ...string) (trans Translator)

FindTranslator trys to find a Translator based on an array of locales and returns the first one it can find, otherwise returns the fallback translator.

func (*UniversalTranslator) GetFallback

func (t *UniversalTranslator) GetFallback() Translator

GetFallback returns the fallback locale

func (*UniversalTranslator) GetTranslator

func (t *UniversalTranslator) GetTranslator(locale string) Translator

GetTranslator returns the specified translator for the given locale, or fallback if not found