translate

Documentation

Overview

Package translate is a highly space and memory optimized l10n (localization) library.

Translation strings are held, per language, in text files (either YAML or JSON), and compile into .gtr or .gtr.gz (gzip compressed) files.

Translations can be referenced in Go code either by an index, or a namespace and translation ID.

Referencing by index is the fastest, most efficient, and what this library was built for. Indexes are stored as constants in generated Go files by namespace.

Translation data and rules are stored in optimized blobs similar to how Go’s native i18n package stores its data.

Index

• Constants
• type Language
  • func (l *Language) FallbackName() string
  • func (l *Language) Get(index TransIndex, args ...interface{}) (string, error)
  • func (l *Language) GetNamed(namespace, translationID string, args ...interface{}) (string, error)
  • func (l *Language) GetPlural(index TransIndex, pluralCount uint, args ...interface{}) (string, error)
  • func (l *Language) GetPluralNamed(namespace string, translationID string, pluralCount uint, args ...interface{}) (string, error)
  • func (l *Language) LanguageIdentifier() string
  • func (l *Language) LanguageTag() language.Tag
  • func (l *Language) MessagePrinter() *message.Printer
  • func (l *Language) MustGet(index TransIndex, args ...interface{}) string
  • func (l *Language) MustGetNamed(namespace string, translationID string, args ...interface{}) string
  • func (l *Language) MustGetPlural(index TransIndex, pluralCount uint, args ...interface{}) string
  • func (l *Language) MustGetPluralNamed(namespace string, translationID string, pluralCount uint, args ...interface{}) string
  • func (l *Language) Name() string
  • func (l *Language) NumTranslations() uint32
  • func (l *Language) SaveGTR(w io.Writer, isCompressed bool) error
  • func (l *Language) SaveGTRDict(w io.Writer, isCompressed bool) error
  • func (l *Language) SaveGTRVarsDict(w io.Writer, isCompressed bool) error
  • func (l *Language) SaveGoDictionaries(outputDirectory, GoDictHeader string) (err error, numUpdated uint)
  • func (l *Language) SetFallback(fallbackLanguage *Language) error
  • func (l *Language) String() string
  • func (l *Language) TimeLocalizer() (*lctime.Localizer, error)
  • func (l *Language) TranslationIDLookup(index TransIndex) (val string, ok bool)
• type LanguageBinaryFile
  • func (lf LanguageBinaryFile) Load(r io.Reader, isCompressed bool) (*Language, error)
  • func (lf LanguageBinaryFile) LoadDefault(r io.Reader, isCompressed bool) (*Language, error)
  • func (lf LanguageBinaryFile) LoadDictionary(r io.Reader, isCompressed bool) (err error, ok bool)
  • func (lf LanguageBinaryFile) LoadDictionaryVars(r io.Reader, isCompressed bool) (err error)
• type LanguageFile
  • func (ll LanguageFile) ClearCurrentDictionary() bool
  • func (ll LanguageFile) HasCurrentDictionary() bool
• type LanguageTextFile
  • func (lf LanguageTextFile) Load(r io.Reader, allowBigStrings bool) (retLang *Language, retWarnings []string, retErrors error)
  • func (lf LanguageTextFile) LoadDefault(r io.Reader, allowBigStrings bool) (retLang *Language, retWarnings []string, retErrors error)
• type TransIndex

Constants

const (
	LF_YAML = iota + LanguageTextFile(lf_DO_NOT_USE)
	LF_JSON
	LF_JSON_AllowTrailingComma
)

const (
	ErrDictionaryDoesNotMatch = "Dictionary does not match"
)

Types

type Language

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

Language is the primary structure for this library that holds all the namespaces and translations

func (*Language) FallbackName

func (l *Language) FallbackName() string

FallbackName returns the fallback language identifier

func (*Language) Get

func (l *Language) Get(index TransIndex, args ...interface{}) (string, error)

Get retrieves a non-plural translation with a TransIndex.

It uses either a “^” plurality rule if found, and the first plurality rule otherwise.

func (*Language) GetNamed

func (l *Language) GetNamed(namespace, translationID string, args ...interface{}) (string, error)

GetNamed retrieves a non-plural translation with a namespace and Translation ID.

It uses either a “^” plurality rule if found, and the first plurality rule otherwise.

func (*Language) GetPlural

func (l *Language) GetPlural(index TransIndex, pluralCount uint, args ...interface{}) (string, error)

GetPlural retrieves a plural translation with a TransIndex.

CurLang.MissingPluralRule is returned if a plurality rule match is not found.

func (*Language) GetPluralNamed

func (l *Language) GetPluralNamed(namespace string, translationID string, pluralCount uint, args ...interface{}) (string, error)

GetPluralNamed retrieves a plural translation with a namespace and Translation ID.

CurLang.MissingPluralRule is returned if a plurality rule match is not found.

func (*Language) LanguageIdentifier

func (l *Language) LanguageIdentifier() string

LanguageIdentifier returns the language identifier

func (*Language) LanguageTag

func (l *Language) LanguageTag() language.Tag

LanguageTag returns the LanguageTag

func (*Language) MessagePrinter

func (l *Language) MessagePrinter() *message.Printer

MessagePrinter returns the MessagePrinter

func (*Language) MustGet

func (l *Language) MustGet(index TransIndex, args ...interface{}) string

MustGet retrieves a non-plural translation with a TransIndex. It returns a blank string when errored.

It uses either a “^” plurality rule if found, and the first plurality rule otherwise.

func (*Language) MustGetNamed

func (l *Language) MustGetNamed(namespace string, translationID string, args ...interface{}) string

MustGetNamed retrieves a non-plural translation with a namespace and Translation ID. It returns a blank string when errored.

It uses either a “^” plurality rule if found, and the first plurality rule otherwise.

func (*Language) MustGetPlural

func (l *Language) MustGetPlural(index TransIndex, pluralCount uint, args ...interface{}) string

MustGetPlural retrieves a plural translation with a TransIndex. It returns a blank string when errored.

CurLang.MissingPluralRule is returned if a plurality rule match is not found.

func (*Language) MustGetPluralNamed

func (l *Language) MustGetPluralNamed(namespace string, translationID string, pluralCount uint, args ...interface{}) string

MustGetPluralNamed retrieves a plural translation with a namespace and Translation ID. It returns a blank string when errored.

CurLang.MissingPluralRule is returned if a plurality rule match is not found.

func (*Language) Name

func (l *Language) Name() string

Name returns the name of the language

func (*Language) NumTranslations

func (l *Language) NumTranslations() uint32

NumTranslations returns the number of translations in the language’s dictionary

func (*Language) SaveGTR

func (l *Language) SaveGTR(w io.Writer, isCompressed bool) error

SaveGTR saves a .gtr language file

func (*Language) SaveGTRDict

func (l *Language) SaveGTRDict(w io.Writer, isCompressed bool) error

SaveGTRDict saves a .gtr dictionary file

func (*Language) SaveGTRVarsDict

func (l *Language) SaveGTRVarsDict(w io.Writer, isCompressed bool) error

SaveGTRVarsDict saves a .gtr variable dictionary file

func (*Language) SaveGoDictionaries

func (l *Language) SaveGoDictionaries(outputDirectory, GoDictHeader string) (err error, numUpdated uint)

SaveGoDictionaries saves the *.go files from the language to $outputDirectory/$namespaceName/TranslationIDs.go. The GoDictHeader is inserted just before the `const` declaration

func (*Language) SetFallback

func (l *Language) SetFallback(fallbackLanguage *Language) error

SetFallback stores the fallback language and is required after (LanguageTextFile|LanguageBinaryFile).Load() operations.

If “Settings.FallbackLanguage” was given for the parent language, the “Settings.LanguageIdentifier” of the given fallbackLanguage must match. If it was not given, fallbackLanguage must be the default language.

A language cannot have itself set as its fallback. That only occurs naturally for the default language.

The fallback language being set must already have its fallback language set. This is required so fallback language loops cannot occur.

func (*Language) String

func (l *Language) String() string

Gives the language name in the debugger

func (*Language) TimeLocalizer

func (l *Language) TimeLocalizer() (*lctime.Localizer, error)

TimeLocalizer returns the TimeLocalizer

func (*Language) TranslationIDLookup

func (l *Language) TranslationIDLookup(index TransIndex) (val string, ok bool)

TranslationIDLookup returns the Namespace name and Translation ID name from a TransIndex, separated by a dot.

As this is only used for debugging purposes, this is not optimized and has to search through all of a namespace’s translations to find a match (only when read from a compiled dictionary file without the variable dictionary loaded).

type LanguageBinaryFile

type LanguageBinaryFile LanguageFile

LanguageBinaryFile is the interface to load .gtr compiled files

const (
	LF_GTR LanguageBinaryFile = iota
)

func (LanguageBinaryFile) Load

func (lf LanguageBinaryFile) Load(r io.Reader, isCompressed bool) (*Language, error)

Load loads a .gtr language file. The default language text file or the dictionary must be loaded first.

Note: Fallback languages still need to be assigned through Language.SetFallback()

func (LanguageBinaryFile) LoadDefault

func (lf LanguageBinaryFile) LoadDefault(r io.Reader, isCompressed bool) (*Language, error)

LoadDefault loads a .gtr language file. This must be the default language. The dictionary must be loaded first.

func (LanguageBinaryFile) LoadDictionary

func (lf LanguageBinaryFile) LoadDictionary(r io.Reader, isCompressed bool) (err error, ok bool)

LoadDictionary loads a compiled dictionary file, which must be done before loading any compiled translation file or non-default-language translation text file.

Returns an error if the dictionary was not loaded during this call.

Returns ok=true if the dictionary was read successfully during this or a previous call to this function.

func (LanguageBinaryFile) LoadDictionaryVars

func (lf LanguageBinaryFile) LoadDictionaryVars(r io.Reader, isCompressed bool) (err error)

LoadDictionaryVars loads a compiled variable dictionary file. This is only used when processing non-default language text files and the compiled dictionary is being loaded.

type LanguageFile

type LanguageFile int

LanguageFile is the base type to load language files

func (LanguageFile) ClearCurrentDictionary

func (ll LanguageFile) ClearCurrentDictionary() bool

ClearCurrentDictionary erases the stored dictionary used for LanguageTextFile.Load() and LanguageBinaryFile.Load(). Languages that have mismatched dictionaries are incompatible. Returns if dictionary was already loaded

func (LanguageFile) HasCurrentDictionary

func (ll LanguageFile) HasCurrentDictionary() bool

HasCurrentDictionary returns if there is a stored dictionary already loaded (for LanguageTextFile.Load() and LanguageBinaryFile.Load())

type LanguageTextFile

type LanguageTextFile LanguageFile

LanguageTextFile is the interface to load translation text files

func (LanguageTextFile) Load

func (lf LanguageTextFile) Load(r io.Reader, allowBigStrings bool) (retLang *Language, retWarnings []string, retErrors error)

Load loads (yaml or json) a language text file. The default language or the dictionary must be loaded first. retLang is still returned when there are warnings but no errors.

Note: Fallback languages still need to be assigned through Language.SetFallback()

func (LanguageTextFile) LoadDefault

func (lf LanguageTextFile) LoadDefault(r io.Reader, allowBigStrings bool) (retLang *Language, retWarnings []string, retErrors error)

LoadDefault loads (yaml or json) the default language text file (and the dictionary). This must be called before reading other languages (unless LanguageBinaryFile.LoadDictionary was already called). retLang is still returned when there are warnings but no errors.

type TransIndex

type TransIndex uint32

TransIndex is the type used for quick Translation ID lookup. Their values are stored as constants in generated Go files by namespace.