Documentation

Localization features provide a convenient way to retrieve strings in various languages, allowing you to easily support multiple languages within your application. Language strings are stored in files within the ./locales directory. Within this directory there should be a subdirectory for each language supported by the application:
1
│   main.go
2
└───locales
3
    ├───el-GR
4
    │       home.yml
5
    ├───en-US
6
    │       home.yml
7
    └───zh-CN
8
            home.yml
Copied!
The default language for your application is the first registered language.
1
app := iris.New()
2
​
3
// First parameter: Glob filpath patern,
4
// Second variadic parameter: Optional language tags,
5
// the first one is the default/fallback one.
6
app.I18n.Load("./locales/*/*", "en-US", "el-GR", "zh-CN")
Copied!
Or if you load all languages by:
1
app.I18n.Load("./locales/*/*")
2
// Then set the default language using:
3
app.I18n.SetDefault("en-US")
Copied!
Load embedded locales
You may want to embed locales with a go-bindata tool within your application executable.
1.install a go-bindata tool, e.g.
$ go get -u github.com/go-bindata/go-bindata/...
2.embed local files to your application
$ go-bindata -o locales.go ./locales/...
3.use the LoadAssets method to initialize and load the languages
^ The AssetNames and Asset functions are generated by go-bindata
1
ap.I18n.LoadAssets(AssetNames, Asset, "en-US", "el-GR", "zh-CN")
Copied!
Defining Translations
Locale files can be written at YAML(recommended), JSON, TOML or INI form.
Each file should contain keys. Keys can have sub-keys(we call them "sections") too.
Each key's value should be of form string or map containing by its translated text (or template) or/and its pluralized key-values.
Iris i18n module supports pluralization out-of-the-box, see below.
Fmt Style
1
hi: "Hi %s!"
Copied!
1
ctx.Tr("Hi", "John")
2
// Outputs: Hi John!
Copied!
Template
1
hi: "Hi {{.Name}}!"
Copied!
1
ctx.Tr("Hi", iris.Map{"Name": "John"})
2
// Outputs: Hi John!
Copied!
Pluralization
Iris i18n supports plural variables. To define a per-locale variable you must define a new section of Vars key.
The acceptable keys for variables are:
one
"=x" where x is a number
"<x"
other
format
Example:
1
Vars:
2
  - Minutes:
3
      one: "minute"
4
      other: "minutes"
5
  - Houses:
6
      one: "house"
7
      other: "houses"
Copied!
Then, each message can use this variable, here's how:
1
# Using variables in raw string
2
YouLate: "You are %[1]d ${Minutes} late."
3
# [x] is the argument position,
4
# variables always have priority other fmt-style arguments,
5
# that's why we see [1] for houses and [2] for the string argument.
6
HouseCount: "%[2]s has %[1]d ${Houses}."
Copied!
1
ctx.Tr("YouLate", 1)
2
// Outputs: You are 1 minute late.
3
ctx.Tr("YouLate", 10)
4
// Outputs: You are 10 minutes late.
5
​
6
ctx.Tr("HouseCount", 2, "John")
7
// Outputs: John has 2 houses.
Copied!
You can select what message will be shown based on a given plural count.
Except variables, each message can also have its plural form too!
Acceptable keys:
zero
one
two
"=x"
"<x"
">x"
other
Let's create a simple plural-featured message, it can use the Minutes variable we created above too.
1
FreeDay:
2
  "=3": "You have three days and %[2]d ${Minutes} off." # "FreeDay" 3, 15
3
  one:  "You have a day off." # "FreeDay", 1
4
  other: "You have %[1]d free days." # "FreeDay", 5
Copied!
1
ctx.Tr("FreeDay", 3, 15)
2
// Outputs: You have three days and 15 minutes off.
3
ctx.Tr("FreeDay", 1)
4
// Outputs: You have a day off.
5
ctx.Tr("FreeDay", 5)
6
// Outputs: You have 5 free days.
Copied!
Let's continue with a bit more advanced example, using template text + functions + plural + variables.
1
Vars:
2
  - Houses:
3
      one: "house"
4
      other: "houses"
5
  - Gender:
6
      "=1": "She"
7
      "=2": "He"
8
​
9
VarTemplatePlural:
10
  one: "${Gender} is awesome!"
11
  other: "other (${Gender}) has %[3]d ${Houses}."
12
  "=5": "{{call .InlineJoin .Names}} are awesome."
Copied!
1
const (
2
    female = iota + 1
3
    male
4
)
5
​
6
ctx.Tr("VarTemplatePlural", iris.Map{
7
    "PluralCount": 5,
8
    "Names":       []string{"John", "Peter"},
9
    "InlineJoin": func(arr []string) string {
10
        return strings.Join(arr, ", ")
11
    },
12
})
13
// Outputs: John, Peter are awesome
14
​
15
ctx.Tr("VarTemplatePlural", 1, female)
16
// Outputs: She is awesome!
17
​
18
ctx.Tr("VarTemplatePlural", 2, female, 5)
19
// Outputs: other (She) has 5 houses.
Copied!
Sections
If the key is not a reserved one (e.g. one, two...) then it acts as a sub section. The sections are separated by dot characters (.).
1
Welcome:
2
  Message: "Welcome {{.Name}}"
Copied!
1
ctx.Tr("Welcome.Message", iris.Map{"Name": "John"})
2
// Outputs: Welcome John
Copied!
Determining The Current Locale
You may use the context.GetLocale method to determine the current locale or check if the locale is a given value:
1
func(ctx iris.Context) {
2
    locale := ctx.GetLocale()
3
    // [...]
4
}
Copied!
The Locale interface looks like this.
1
// Locale is the interface which returns from a `Localizer.GetLocale` metod.
2
// It serves the transltions based on "key" or format. See `GetMessage`.
3
type Locale interface {
4
    // Index returns the current locale index from the languages list.
5
    Index() int
6
    // Tag returns the full language Tag attached tothis Locale,
7
    // it should be uniue across different Locales.
8
    Tag() *language.Tag
9
    // Language should return the exact languagecode of this `Locale`
10
    //that the user provided on `New` function.
11
    //
12
    // Same as `Tag().String()` but it's static.
13
    Language() string
14
    // GetMessage should return translated text based n the given "key".
15
    GetMessage(key string, args ...interface{}) string
16
}
Copied!
Retrieving Translation
Use of context.Tr method as a shortcut to get a translated text for this request.
1
func(ctx iris.Context) {
2
    text := ctx.Tr("hi", "name")
3
    // [...]
4
}
Copied!
Inside Views
1
func(ctx iris.Context) {
2
    ctx.View("index.html", iris.Map{
3
        "tr": ctx.Tr,
4
    })
5
}
Copied!

📁File Server - Previous

Serve files from Context

Next - 🌎Localization

Sitemap

Last modified 1yr ago

Export as PDF

Copy link

Contents

Load embedded locales

Defining Translations

Determining The Current Locale

Retrieving Translation

Inside Views