Localization

Introduction

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/*/*")
Copied!
Then set the default language using:
1
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

Each file should contain keys with translated text or template values.

Fmt Style

1
hi: "Hi %s"
Copied!
YAML, TOML, JSON, INI files.

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!

INI Sections

INI Sections are separated by dot ".". The second optional value can be a map or a struct as the template value like the rest file formats.
1
func(ctx iris.Context) {
2
text := ctx.Tr("cart.checkout", iris.Map{"Param": "a value"})
3
// [...]
4
}
Copied!

Inside Views

1
func(ctx iris.Context) {
2
ctx.View("index.html", iris.Map{
3
"tr": ctx.Tr,
4
})
5
}
Copied!

Example

1
package main
2
3
import (
4
"github.com/kataras/iris/v12"
5
)
6
7
func newApp() *iris.Application {
8
app := iris.New()
9
10
// Configure i18n.
11
// First parameter: Glob filpath patern,
12
// Second variadic parameter: Optional language tags, the first one is the default/fallback one.
13
app.I18n.Load("./locales/*/*.ini", "en-US", "el-GR", "zh-CN")
14
// app.I18n.LoadAssets for go-bindata.
15
16
// Default values:
17
// app.I18n.URLParameter = "lang"
18
// app.I18n.Subdomain = true
19
//
20
// Set to false to disallow path (local) redirects,
21
// see https://github.com/kataras/iris/issues/1369.
22
// app.I18n.PathRedirect = true
23
24
app.Get("/", func(ctx iris.Context) {
25
hi := ctx.Tr("hi", "iris")
26
27
locale := ctx.GetLocale()
28
29
ctx.Writef("From the language %s translated output: %s", locale.Language(), hi)
30
})
31
32
app.Get("/some-path", func(ctx iris.Context) {
33
ctx.Writef("%s", ctx.Tr("hi", "iris"))
34
})
35
36
app.Get("/other", func(ctx iris.Context) {
37
language := ctx.GetLocale().Language()
38
39
fromFirstFileValue := ctx.Tr("key1")
40
fromSecondFileValue := ctx.Tr("key2")
41
ctx.Writef("From the language: %s, translated output:\n%s=%s\n%s=%s",
42
language, "key1", fromFirstFileValue,
43
"key2", fromSecondFileValue)
44
})
45
46
// using in inside your views:
47
view := iris.HTML("./views", ".html")
48
app.RegisterView(view)
49
50
app.Get("/templates", func(ctx iris.Context) {
51
ctx.View("index.html", iris.Map{
52
"tr": ctx.Tr, // word, arguments... {call .tr "hi" "iris"}}
53
})
54
55
// Note that,
56
// Iris automatically adds a "tr" global template function as well,
57
// the only difference is the way you call it inside your templates and
58
// that it accepts a language code as its first argument.
59
})
60
//
61
62
return app
63
}
64
65
func main() {
66
app := newApp()
67
68
// go to http://localhost:8080/el-gr/some-path
69
// ^ (by path prefix)
70
//
71
// or http://el.mydomain.com8080/some-path
72
// ^ (by subdomain - test locally with the hosts file)
73
//
74
// or http://localhost:8080/zh-CN/templates
75
// ^ (by path prefix with uppercase)
76
//
77
// or http://localhost:8080/some-path?lang=el-GR
78
// ^ (by url parameter)
79
//
80
// or http://localhost:8080 (default is en-US)
81
// or http://localhost:8080/?lang=zh-CN
82
//
83
// go to http://localhost:8080/other?lang=el-GR
84
// or http://localhost:8080/other (default is en-US)
85
// or http://localhost:8080/other?lang=en-US
86
//
87
// or use cookies to set the language.
88
app.Listen(":8080", iris.WithSitemap("http://localhost:8080"))
89
}
Copied!

Sitemap

Sitemap translations are automatically set to each route by path prefix if app.I18n.PathRedirect is true or by subdomain if app.I18n.Subdomain is true or by URL query parameter if app.I18n.URLParameter is not empty.
1
GET http://localhost:8080/sitemap.xml
Copied!
1
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
2
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml">
3
<url>
4
<loc>http://localhost:8080/</loc>
5
<xhtml:link rel="alternate" hreflang="en-US" href="http://localhost:8080/"></xhtml:link>
6
<xhtml:link rel="alternate" hreflang="el-GR" href="http://localhost:8080/el-GR/"></xhtml:link>
7
<xhtml:link rel="alternate" hreflang="zh-CN" href="http://localhost:8080/zh-CN/"></xhtml:link>
8
</url>
9
<url>
10
<loc>http://localhost:8080/some-path</loc>
11
<xhtml:link rel="alternate" hreflang="en-US" href="http://localhost:8080/some-path"></xhtml:link>
12
<xhtml:link rel="alternate" hreflang="el-GR" href="http://localhost:8080/el-GR/some-path"></xhtml:link>
13
<xhtml:link rel="alternate" hreflang="zh-CN" href="http://localhost:8080/zh-CN/some-path"></xhtml:link>
14
</url>
15
<url>
16
<loc>http://localhost:8080/other</loc>
17
<xhtml:link rel="alternate" hreflang="en-US" href="http://localhost:8080/other"></xhtml:link>
18
<xhtml:link rel="alternate" hreflang="el-GR" href="http://localhost:8080/el-GR/other"></xhtml:link>
19
<xhtml:link rel="alternate" hreflang="zh-CN" href="http://localhost:8080/zh-CN/other"></xhtml:link>
20
</url>
21
<url>
22
<loc>http://localhost:8080/templates</loc>
23
<xhtml:link rel="alternate" hreflang="en-US" href="http://localhost:8080/templates"></xhtml:link>
24
<xhtml:link rel="alternate" hreflang="el-GR" href="http://localhost:8080/el-GR/templates"></xhtml:link>
25
<xhtml:link rel="alternate" hreflang="zh-CN" href="http://localhost:8080/zh-CN/templates"></xhtml:link>
26
</url>
27
</urlset>
Copied!
Last modified 11mo ago