ut

README

universal-translator

 [](https://semaphoreci.com/joeybloggs/universal-translator) [](https://coveralls.io/github/go-playground/universal-translator?branch=master) [](https://goreportcard.com/report/github.com/go-playground/universal-translator) [](https://godoc.org/github.com/go-playground/universal-translator) 

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/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

	universalTraslator, _ = ut.New("en", "en", "en_CA", "nl", "fr")

	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
	en.Add("welcome", "Welcome {0} to our test")

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

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

	// 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)

	// 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 ErrLocaleNotFound
  • func (e *ErrLocaleNotFound) 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 string, supportedLocales ...string) (*UniversalTranslator, error)
  • func (t *UniversalTranslator) FindTranslator(locales ...string) (trans 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 ErrLocaleNotFound

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

ErrLocaleNotFound is the error signifying a locale which could not be found

func (*ErrLocaleNotFound) Error

func (e *ErrLocaleNotFound) Error() string

Error returns ErrLocaleNotFound'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)

	// 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) 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) 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) error

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

	// 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 string, supportedLocales ...string) (*UniversalTranslator, error)

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

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) GetTranslator

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

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