Improved docs

README.md

@@ -10,12 +10,14 @@ 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. 
-- Language codes are automatically simplified from the form "en_UK" to "en" if the formed isn't available.
+- 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.
+- 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
 

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 {

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