v.io: v.io/v23/i18n Index | Files

package i18n

import "v.io/v23/i18n"

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.


Package Files


func FormatParams Uses

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 Uses

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

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

type Catalogue Uses

type Catalogue struct {
    // contains filtered or unexported fields

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

func Cat Uses

func Cat() (result *Catalogue)

Cat returns the default Catalogue.

func (*Catalogue) Format Uses

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 Uses

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 Uses

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 Uses

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

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

func (*Catalogue) Output Uses

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 Uses

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 Uses

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 Uses

type LangID string

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

const NoLangID LangID = ""

NoLangID is the empty LangID.

func BaseLangID Uses

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 Uses

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 Uses

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 Uses

func NormalizeLangID(langID string) LangID

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

type MsgID Uses

type MsgID string

MsgID identifies a message, without specifying its language.

Package i18n imports 8 packages (graph) and is imported by 124 packages. Updated 2020-06-08. Refresh now. Tools for package owners.