diff --git a/README.md b/README.md index cbeb17c..c25322e 100644 --- a/README.md +++ b/README.md @@ -9,13 +9,15 @@ GNU gettext utilities for Go. #Features -- Implements GNU gettext support in native Go. -- It works with UTF-8 encoding as it's the default for Go language. -- Supports pluralization rules. -- Ready to use inside Go templates. -- Safe for concurrent use accross multiple goroutines. +- Implements GNU gettext support in native Go. +- Safe for concurrent use accross multiple goroutines. +- It works with UTF-8 encoding as it's the default for Go language. +- Unit tests available - Language codes are automatically simplified from the form "en_UK" to "en" if the formed isn't available. -- Unit tests available +- Ready to use inside Go templates. +- Support for pluralization rules. +- Support for variables inside translation strings using the Go's [fmt package syntax](https://golang.org/pkg/fmt/) + # Installation @@ -39,6 +41,46 @@ go get github.com/leonelquinteros/gotext Refer to the Godoc package documentation at (https://godoc.org/github.com/leonelquinteros/gotext) +# Locales directories structure + +The package will asume a directories structure starting with a base path that will be provided to the package configuration +or to object constructors depending on the use, but either will use the same convention to lookup inside the base path. + +Inside the base directory where will be the language directories named using the language and country 2-letter codes (en_US, es_AR, ...). +All package functions can lookup after the simplified version for each language in case the full code isn't present but the more general language code exists. +So if the language set is "en_UK", but there is no directory named after that code and there is a directory named "en", +all package functions will be able to resolve this generalization and provide translations for the more general library. + +The language codes are assumed to be [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) codes (2-letter codes). +That said, most functions will work with any coding standard as long the directory name matches the language code set on the configuration. + +A normal library directory structure may look like: + +``` +/path/to/locales +/path/to/locales/en_US +/path/to/locales/en_US/default.po +/path/to/locales/en_US/extras.po +/path/to/locales/en_UK +/path/to/locales/en_UK/default.po +/path/to/locales/en_UK/extras.po +/path/to/locales/en_AU +/path/to/locales/en_AU/default.po +/path/to/locales/en_AU/extras.po +/path/to/locales/es +/path/to/locales/es/default.po +/path/to/locales/es/extras.po +/path/to/locales/es_ES +/path/to/locales/es_ES/default.po +/path/to/locales/es_ES/extras.po +/path/to/locales/fr +/path/to/locales/fr/default.po +/path/to/locales/fr/extras.po +``` + +And so on... + + # About translation function names diff --git a/gotext.go b/gotext.go index 8509602..294f817 100644 --- a/gotext.go +++ b/gotext.go @@ -6,18 +6,18 @@ Version 0.9.0 (stable) For quick/simple translations you can use the package level functions directly. import "github.com/leonelquinteros/gotext" - + func main() { // Configure package gotext.Configure("/path/to/locales/root/dir", "en_UK", "domain-name") - + // Translate text from default domain println(gotext.Get("My text on 'domain-name' domain")) - + // Translate text from a different domain without reconfigure println(gotext.GetD("domain2", "Another text on a different domain")) } - + */ package gotext diff --git a/locale.go b/locale.go index 58b95f3..1abc963 100644 --- a/locale.go +++ b/locale.go @@ -6,6 +6,32 @@ import ( "path" ) +/* +Locale wraps the entire i18n collection for a single language (locale) +It's used by the package functions, but it can also be used independently to handle +multiple languages at the same time by working with this object. + +Example: + + import "github.com/leonelquinteros/gotext" + + func main() { + // Create Locale with library path and language code + l := gotext.NewLocale("/path/to/i18n/dir", "en_US") + + // Load domain '/path/to/i18n/dir/en_US/default.po' + l.AddDomain("default") + + // Translate text from default domain + println(l.Get("Translate this")) + + // Load different domain ('/path/to/i18n/dir/en_US/extras.po') + l.AddDomain("extras") + + // Translate text from domain + println(l.GetD("extras", "Translate this")) + } +*/ type Locale struct { // Path to locale files. path string @@ -72,6 +98,7 @@ func (l *Locale) GetD(dom, str string, vars ...interface{}) string { } // GetND retrieves the (N)th plural form translation in the given domain for a given string. +// If n == 0, usually the singular form of the string is returned as defined in the PO file. // Supports optional parameters (vars... interface{}) to be inserted on the formatted string using the fmt.Printf syntax. func (l *Locale) GetND(dom, str, plural string, n int, vars ...interface{}) string { if l.domains != nil { diff --git a/po.go b/po.go index 0879eba..556c344 100644 --- a/po.go +++ b/po.go @@ -42,7 +42,24 @@ func (t *translation) getN(n int) string { return t.pluralId } -// Po type handles the content of any PO file. +/* +Po parses the content of any PO file and provides all the translation functions needed. + +Example: + + import "github.com/leonelquinteros/gotext" + + func main() { + // Create po object + po := new(Po) + + // Parse .po file + po.ParseFile("/path/to/po/file/translations.po") + + // Get translation + println(po.Get("Translate this")) + } +*/ type Po struct { // Storage translations map[string]*translation