gettext

README

gettext in golang

go-gettext is a pure Go implementation of the GNU Gettext internationalisation API. It loads the binary catalogs generated by msgfmt by memory mapping them, so there is very little overhead at startup. Translations are looked up using the data structures in the catalog directly (either a binary search or hash table lookup).

In addition to the basic Gettext API it supports the NGettext and PGettext variants, supporting plural translations and translations requiring a context string respectively.

Example

import "github.com/snapcore/go-gettext"

//go:embed translations
var assets embed.FS

domain := &gettext.TextDomain{
	Name:      "messages",
	LocaleDir: "./translations",
	LocaleFS:  assets,  // leave away to use the filesystem directly
}
// or use domain.Locale(lang...) to open a different locale's catalog
locale := domain.UserLocale()

fmt.Println(locale.Gettext("hello from gettext"))

for i := 0; i <= 10; i++ {
	fmt.Printf(locale.NGettext("%d thing\n", "%d things\n", uint32(i)), i)
}

TODO

• parse mofiles
• compile plural forms
• non-utf8 mo files (possible wontfix)
• gettext
• ngettext
• pgettext/npgettext
• managing mo files / sane API

Documentation

Index

• Constants
• func DefaultResolver(root string, locale string, domain string) string
• func UserLanguages() []string
• type Catalog
  • func ParseMO(file *os.File) (Catalog, error)
  • func (c Catalog) Gettext(msgid string) string
  • func (c Catalog) NGettext(msgid, msgidPlural string, n uint32) string
  • func (c Catalog) NPGettext(msgctxt, msgid, msgidPlural string, n uint32) string
  • func (c Catalog) PGettext(msgctxt, msgid string) string
• type PathResolver
• type TextDomain
  • func (t *TextDomain) Locale(languages ...string) Catalog
  • func (t *TextDomain) Preload(locales ...string)
  • func (t *TextDomain) UserLocale() Catalog
• type Translations
  • func NewTranslations(localeDir, domain string, resolver PathResolver) Translations

Constants

const DefaultLocaleDir = "/usr/share/locale"

Functions

func DefaultResolver

func DefaultResolver(root string, locale string, domain string) string

DefaultResolver resolves paths in the standard format of: <root>/<locale>/LC_MESSAGES/<domain>.mo

func UserLanguages

func UserLanguages() []string

UserLanguages returns a list of the user's preferred languages

These are in the form of POSIX locale identifiers. This lookup is based on the logic of libintl's guess_category_value()

Types

type Catalog

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

Catalog of translations for a given locale.

func ParseMO

func ParseMO(file *os.File) (Catalog, error)

ParseMO parses a mo file into a Catalog if possible.

func (Catalog) Gettext

func (c Catalog) Gettext(msgid string) string

Gettext returns a translation of the provided message.

If no translation is available, the original message is returned.

func (Catalog) NGettext

func (c Catalog) NGettext(msgid, msgidPlural string, n uint32) string

NGettext returns a translation of the provided message using the appropriate plural form.

Different languages have different rules for handling plural forms. The NGettext method will pick an appropriate form based on the integer passed to it. Normally the translated message will be a format string:

const number = 42
fmt.Printf(c.NGettext("%d dog", "%d dogs", number), number)

If no translation is available, one of msgid and msgidPlural will be returned, according to the plural rule of Germanic languages (i.e. msgid if n==1, and msgidPlural otherwise).

func (Catalog) NPGettext

func (c Catalog) NPGettext(msgctxt, msgid, msgidPlural string, n uint32) string

NPGettext returns a translation of the provided message using the provided context and plural form.

This method combines the functionality of the NGettext and PGettext variants.

func (Catalog) PGettext

func (c Catalog) PGettext(msgctxt, msgid string) string

PGettext returns a translation of the provided message using the provided context.

In some cases, an single message string may be used in multiple places whose translation depends on the context. This can happen with very short message strings, or messages containing homographs.

The PGettext method solves this problem by providing a context string together with the message, which is used to look up the translation.

If no translation is available, the original message is returned without the context.

type PathResolver

type PathResolver func(root string, locale string, domain string) string

PathResolver resolves a path to a mo file

type TextDomain

type TextDomain struct {
	// Name is the name of the text domain
	Name string
	// LocaleDir is the base directory holding translations of the
	// domain.  If it is empty, DefaultLocaleDir will be used if LocaleFS is nil; otherwise the root of LocaleFS will be used.
	LocaleDir string
	// LocaleFS is the filesystem used to access LocaleDir.
	// When nil, the normal OS filesystem will be used.
	LocaleFS fs.FS
	// PathResolver is called to determine the path of a
	// particular locale's translations.  If it is nil then
	// DefaultResolver will be used, which implements the standard
	// gettext directory layout.
	PathResolver PathResolver
	// contains filtered or unexported fields
}

TextDomain represents a collection of translatable strings.

The Locale and UserLocale methods can be used to access translations of those strings in various languages.

func (*TextDomain) Locale

func (t *TextDomain) Locale(languages ...string) Catalog

Locale returns the catalog translations for a list of locales.

If translations are not found in the first locale, the each subsequent one is consulted until a match is found. If no match is found, the original strings are returned.

func (*TextDomain) Preload

func (t *TextDomain) Preload(locales ...string)

Preload a list of locales (if they're available). This is useful if you want to limit IO to a specific time in your app, for example startup. Subsequent calls to Preload or Locale using a locale given here will not do any IO.

func (*TextDomain) UserLocale

func (t *TextDomain) UserLocale() Catalog

UserLocale returns the catalog translations for the user's Locale.

type Translations

type Translations = *TextDomain

Translations is an alias for a TextDomain pointer

Deprecated: this type alias is provided for backwards compatibility. New code should use TextDomain directly.

func NewTranslations

func NewTranslations(localeDir, domain string, resolver PathResolver) Translations

NewTranslations initialises a TextDomain struct, setting the Name, LocaleDir and PathResolver fields.

Deprecated: New code should initialise TextDomain directly.