README

universal-translator

Project status Build Status Coverage Status Go Report Card GoDoc License Gitter

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 implementation 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 CLDR data, v30.0.3
  • 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(s), 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 & Documentation

Please see https://godoc.org/github.com/go-playground/universal-translator for usage docs

Examples:

File formatting

All types, Plain substitution, Cardinal, Ordinal and Range translations can all be contained withing the same file(s); they are only separated for easy viewing.

Examples:
Basic Makeup

NOTE: not all fields are needed for all translation types, see examples

{
    "locale": "en",
    "key": "days-left",
    "trans": "You have {0} day left.",
    "type": "Cardinal",
    "rule": "One",
    "override": false
}
Field Description
locale The locale for which the translation is for.
key The translation key that will be used to store and lookup each translation; normally it is a string or integer.
trans The actual translation text.
type The type of translation Cardinal, Ordinal, Range or "" for a plain substitution(not required to be defined if plain used)
rule The plural rule for which the translation is for eg. One, Two, Few, Many or Other.(not required to be defined if plain used)
override If you wish to override an existing translation that has already been registered, set this to 'true'. 99% of the time there is no need to define it.

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.

License

Distributed under MIT License, please see license file in code for more details.

Documentation

Index

Constants

This section is empty.

Variables

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

Functions

This section is empty.

Types

type ErrBadParamSyntax

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

    ErrBadParamSyntax is the error representing a bad parameter definition in a translation eg. This is a {must-be-int}

    func (*ErrBadParamSyntax) Error

    func (e *ErrBadParamSyntax) Error() string

      Error returns ErrBadParamSyntax error message

      type ErrBadPluralDefinition

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

        ErrBadPluralDefinition is the error representing an incorrect plural definition usually found within translations defined within files during the import process.

        func (*ErrBadPluralDefinition) Error

        func (e *ErrBadPluralDefinition) Error() string

          Error returns ErrBadPluralDefinition's internal error text

          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 ErrMissingBracket

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

                        ErrMissingBracket is the error representing a missing bracket in a translation eg. This is a {0 <-- missing ending '}'

                        func (*ErrMissingBracket) Error

                        func (e *ErrMissingBracket) Error() string

                          Error returns ErrMissingBracket error message

                          type ErrMissingLocale

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

                            ErrMissingLocale is the error representing an expected locale that could not be found aka locale not registered with the UniversalTranslator Instance

                            func (*ErrMissingLocale) Error

                            func (e *ErrMissingLocale) Error() string

                              Error returns ErrMissingLocale'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

                                  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 ImportExportFormat

                                          type ImportExportFormat uint8

                                            ImportExportFormat is the format of the file import or export

                                            const (
                                            	FormatJSON ImportExportFormat = iota
                                            )

                                              supported Export Formats

                                              type Translator

                                              type Translator interface {
                                              	locales.Translator
                                              
                                              	// adds a normal translation for a particular language/locale
                                              	// {#} is the only replacement type accepted and are ad infinitum
                                              	// 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) Export

                                                      func (t *UniversalTranslator) Export(format ImportExportFormat, dirname string) error

                                                        Export writes the translations out to a file on disk.

                                                        NOTE: this currently only works with string or int translations keys.

                                                        func (*UniversalTranslator) FindTranslator

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

                                                          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) (trans Translator, found bool)

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

                                                              func (*UniversalTranslator) Import

                                                              func (t *UniversalTranslator) Import(format ImportExportFormat, dirnameOrFilename string) error

                                                                Import reads the translations out of a file or directory on disk.

                                                                NOTE: this currently only works with string or int translations keys.

                                                                func (*UniversalTranslator) ImportByReader

                                                                func (t *UniversalTranslator) ImportByReader(format ImportExportFormat, reader io.Reader) error

                                                                  ImportByReader imports the the translations found within the contents read from the supplied reader.

                                                                  NOTE: generally used when assets have been embedded into the binary and are already in memory.

                                                                  func (*UniversalTranslator) VerifyTranslations

                                                                  func (t *UniversalTranslator) VerifyTranslations() (err error)

                                                                    VerifyTranslations runs through all locales and identifies any issues eg. missing plural rules for a locale

                                                                    Directories

                                                                    Path Synopsis
                                                                    _examples