docs

fixes https://github.com/nicksnyder/go-i18n/issues/105

3 files changed, 21 insertions, 10 deletions

diff --git a/README.md b/README.md
index 24ceef9..a84fbd7 100644
--- a/README.md
+++ b/README.md
@@ -2,16 +2,16 @@
 
 go-i18n is a Go [package](#package-i18n) and a [command](#command-goi18n) that helps you translate Go programs into multiple languages.
 
-* Supports [pluralized strings](http://cldr.unicode.org/index/cldr-spec/plural-rules) for all 200+ languages in the [Unicode Common Locale Data Repository (CLDR)](http://www.unicode.org/cldr/charts/28/supplemental/language_plural_rules.html).
-  * Code and tests are [automatically generated](https://github.com/nicksnyder/go-i18n/tree/master/i18n/language/codegen) from [CLDR data](http://cldr.unicode.org/index/downloads).
-* Supports strings with named variables using [text/template](http://golang.org/pkg/text/template/) syntax.
-* Supports message files of any format (e.g. JSON, TOML, YAML, etc.).
-* [Documented](http://godoc.org/github.com/nicksnyder/go-i18n) and [tested](https://travis-ci.org/nicksnyder/go-i18n)!
+- Supports [pluralized strings](http://cldr.unicode.org/index/cldr-spec/plural-rules) for all 200+ languages in the [Unicode Common Locale Data Repository (CLDR)](http://www.unicode.org/cldr/charts/28/supplemental/language_plural_rules.html).
+  - Code and tests are [automatically generated](https://github.com/nicksnyder/go-i18n/tree/master/i18n/language/codegen) from [CLDR data](http://cldr.unicode.org/index/downloads).
+- Supports strings with named variables using [text/template](http://golang.org/pkg/text/template/) syntax.
+- Supports message files of any format (e.g. JSON, TOML, YAML, etc.).
+- [Documented](http://godoc.org/github.com/nicksnyder/go-i18n) and [tested](https://travis-ci.org/nicksnyder/go-i18n)!
 
 ## Versions
 
-* v1 is available at 1.x.x tags.
-* v2 is available at 2.x.x tags.
+- v1 is available at 1.x.x tags.
+- v2 is available at 2.x.x tags.
 
 This README always documents the latest version (i.e. v2).
 
@@ -29,6 +29,12 @@ Create a Bundle to use for the lifetime of your application.
 bundle := &i18n.Bundle{DefaultLanguage: language.English}
 ```
 
+Load translations into your bundle during initialization.
+
+```go
+bundle.LoadMessageFile("en-US.yaml")
+```
+
 Create a Localizer to use for a set of language preferences.
 
 ```go
@@ -108,9 +114,9 @@ bundle.MustLoadMessageFile("active.es.toml")
 
 ## For more information and examples:
 
-* Read the [documentation](http://godoc.org/github.com/nicksnyder/go-i18n/v2/i18n).
-* Look at the [code examples](https://github.com/nicksnyder/go-i18n/blob/master/v2/i18n/example_test.go) and [tests](https://github.com/nicksnyder/go-i18n/blob/master/v2/i18n/localizer_test.go).
-* Look at an example [application](https://github.com/nicksnyder/go-i18n/tree/master/v2/example).
+- Read the [documentation](http://godoc.org/github.com/nicksnyder/go-i18n/v2/i18n).
+- Look at the [code examples](https://github.com/nicksnyder/go-i18n/blob/master/v2/i18n/example_test.go) and [tests](https://github.com/nicksnyder/go-i18n/blob/master/v2/i18n/localizer_test.go).
+- Look at an example [application](https://github.com/nicksnyder/go-i18n/tree/master/v2/example).
 
 ## License
 
diff --git a/v2/i18n/bundle.go b/v2/i18n/bundle.go
index 05804ed..a2c4e45 100644
--- a/v2/i18n/bundle.go
+++ b/v2/i18n/bundle.go
@@ -16,6 +16,8 @@ type UnmarshalFunc = internal.UnmarshalFunc
 // Bundle stores a set of messages and pluralization rules.
 // Most applications only need a single bundle
 // that is initialized early in the application's lifecycle.
+// It is not goroutine safe to modify the bundle while Localizers
+// are reading from it.
 type Bundle struct {
 	// DefaultLanguage is the default language of the bundle.
 	DefaultLanguage language.Tag
diff --git a/v2/i18n/doc.go b/v2/i18n/doc.go
index 7b56a71..1903082 100644
--- a/v2/i18n/doc.go
+++ b/v2/i18n/doc.go
@@ -4,6 +4,9 @@
 // Create a Bundle to use for the lifetime of your application.
 //     bundle := &i18n.Bundle{DefaultLanguage: language.English}
 //
+// Load translations into your bundle during initialization.
+//     bundle.LoadMessageFile("en-US.yaml")
+//
 // Create a Localizer to use for a set of language preferences.
 //     func(w http.ResponseWriter, r *http.Request) {
 //         lang := r.FormValue("lang")