i18n

Documentation

Overview

Package i18n implements internationalization of formatted message strings in different languages.

Typical usage:

cat := i18n.Cat()   // get default Catalogue
outputString = cat.Format(language, msgID, "1st", "2nd", "3rd", "4th")

i18n.Catalogue maps language names and message identifiers to message format strings. The intent is to provide a primitive form of Sprintf(), where the format string can depend upon the language.

i18n.MsgID is a string that identitifies a set of message format strings that have the same meaning, but may be available in multiple languages.

i18n.Lang is a string that identifies a language.

A message format string is a string containing substrings of the form {<number>} which are replaced by the corresponding position parameter (numbered from 1), or {_}, which is replaced by all otherwise unused parameters. If a substring is of the form {:<number>}, {<number>:}, {:<number>:}, {:_}, {_:}, or {:_:}, and the corresponding parameters are not the empty string, the parameter is preceded by ": " or followed by ":" or both, respectively. For example, if the format:

{3:} foo {2} bar{:_} ({3})

is used with the cat.Format example above, it yields:

3rd: foo 2nd bar: 1st 4th (3rd)

The positional parameters may have any type, and are printed in their default formatting. If particular formatting is desired, the parameter should be converted to a string first. In principle, the default formating for a parameter may depend on LangID.

Index

• func FormatParams(formatStr string, v ...interface{}) (result string)
• func WithLangID(ctx *context.T, langID LangID) *context.T
• type Catalogue
  • func Cat() (result *Catalogue)
  • func (cat *Catalogue) Format(langID LangID, msgID MsgID, v ...interface{}) string
  • func (cat *Catalogue) Lookup(langID LangID, msgID MsgID) (result string)
  • func (cat *Catalogue) Merge(r io.Reader) error
  • func (cat *Catalogue) MergeFromFile(filename string) (err error)
  • func (cat *Catalogue) Output(w io.Writer) error
  • func (cat *Catalogue) Set(langID LangID, msgID MsgID, newFormat string) (oldFormat string)
  • func (cat *Catalogue) SetWithBase(langID LangID, msgID MsgID, newFormat string) (oldFormat string)
• type LangID
  • func BaseLangID(langID LangID) LangID
  • func GetLangID(ctx *context.T) (langID LangID)
  • func LangIDFromEnv() LangID
  • func NormalizeLangID(langID string) LangID
• type MsgID

Functions

func FormatParams

func FormatParams(formatStr string, v ...interface{}) (result string)

FormatParams returns a copy of format with instances of "{1}", "{2}", ... replaced by the default string representation of v[0], v[1], ... The last instance of the string "{_}" is replaced with a space-separated list of positional parameters unused by other {...} sequences. Missing parameters are replaced with "?".

func WithLangID

func WithLangID(ctx *context.T, langID LangID) *context.T

WithLangID returns a context based on ctx that has the language ID langID.

Types

type Catalogue

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

Catalogue maps (LangID, MsgID) pairs to message format strings.

func Cat

func Cat() (result *Catalogue)

Cat returns the default Catalogue.

func (*Catalogue) Format

func (cat *Catalogue) Format(langID LangID, msgID MsgID, v ...interface{}) string

Format applies FormatParams to the result of Lookup(langID, msgId) and the parameters v. If Lookup fails, the result is the text of the MsgID, and if there are any positional parameters, a colon followed by those parameters.

func (*Catalogue) Lookup

func (cat *Catalogue) Lookup(langID LangID, msgID MsgID) (result string)

Lookup returns the format corresponding to a particular language and MsgID. If no such message is known, any message for BaseLangID(langID) is retrievied. If no such message exists, empty string is returned.

func (*Catalogue) Merge

func (cat *Catalogue) Merge(r io.Reader) error

Merge merges the data in the lines from *r reader into *cat. Each line from *r is parsed with Scanf("%s %s %q"); that is, the first two fields are whitespace separated, and the third is quoted and escaped. If a line starts with a #, or cannot be parsed, the line is ignored. If the line contains at least three non-discarded fields, the first field is treated as LangID, the second as a i18n.MsgID, and the third as a format string in the specified language.

func (*Catalogue) MergeFromFile

func (cat *Catalogue) MergeFromFile(filename string) (err error)

MergeFromFile calls Merge() on the contents of the named file.

func (*Catalogue) Output

func (cat *Catalogue) Output(w io.Writer) error

Output emits the contents of *cat to *w in the format expected by Merge().

func (*Catalogue) Set

func (cat *Catalogue) Set(langID LangID, msgID MsgID, newFormat string) (oldFormat string)

Set sets the format corresponding to msgID in the specified language to formatStr. If formatStr is empty, the corresponding entry is removed. Any previous string is returned.

func (*Catalogue) SetWithBase

func (cat *Catalogue) SetWithBase(langID LangID, msgID MsgID, newFormat string) (oldFormat string)

SetWithBase is like Set, but if newFormat != "", also sets the message for the base language ID if not already set. Equivalent to:

baseLangID := BaseLangID(langID)
if newFormat != "" && baseLangID != langID && cat.Lookup(baseLangID, msgID) == "" {
    cat.Set(baseLangID, msgID, newFormat)
}
return cat.Set(langID, msgID, newFormat)

type LangID

type LangID string

LangID represents the name of a language or locale. By convention it should be an IETF language tag:

http://en.wikipedia.org/wiki/IETF_language_tag

const NoLangID LangID = ""

NoLangID is the empty LangID.

func BaseLangID

func BaseLangID(langID LangID) LangID

BaseLangID returns a base language identifier. It is the first hyphen-separated segment of an IETF Language ID.

func GetLangID

func GetLangID(ctx *context.T) (langID LangID)

GetLangID returns the LangID associated with a context.T, or the empty LangID if there is none.

func LangIDFromEnv

func LangIDFromEnv() LangID

LangIDFromEnv returns a language ID for messages based on the programme's environment variables. This is suitable only for code not running in the context of an RPC; code in an RPC context should use language information from the RPC context.

func NormalizeLangID

func NormalizeLangID(langID string) LangID

NormalizeLangID normalizes a LangID. Currently, the only normalization performed is to translate underbars into hyphens.

type MsgID

type MsgID string

MsgID identifies a message, without specifying its language.