Internationalization (i18n) in Go (Golang): A Complete Guide

Internationalization (i18n) in Go (Golang): A Complete Guide for Developers

Internationalization (i18n) is the process of designing software so that it can be easily adapted for different languages and regions without making changes to the source code. In Go (Golang), there are several mature solutions for this purpose, but the most popular and standardized one is the golang.org/x/text package, which provides powerful tools for working with localization. In this article, we will thoroughly examine how to set up i18n in a Go application using official libraries and best practices.

Key Libraries for i18n in Go

The Go ecosystem offers several approaches to internationalization. Let's look at the key ones:

• golang.org/x/text — the main package from the Go team, supporting Unicode, CLDR (Common Locale Data Repository), and complex pluralization rules.
• github.com/nicksnyder/go-i18n — a popular third-party library with support for JSON, TOML, and YAML translation files, a simple API, and automatic language detection.
• github.com/leonelquinteros/gotext — a lightweight alternative that works with the GNU gettext format (.po/.mo files), ideal for small projects.

In this guide, we will focus on go-i18n as the most balanced solution for web applications, but the concepts apply to any library.

Installing and Configuring go-i18n

First, install the library and the CLI tool for working with translations:

go get github.com/nicksnyder/go-i18n/v2/i18ngo install github.com/nicksnyder/go-i18n/v2/goi18n@latest

Create the project structure:

myapp/├── active.en.json├── active.ru.json├── main.go└── go.mod

Creating Translation Files

The library uses JSON files with translations. Example for English and Russian:

active.en.json

{  "greeting": {    "other": "Hello, {{.Name}}!"  },  "cakes_count": {    "one": "You have {{.Count}} cake.",    "few": "You have {{.Count}} cakes.",    "many": "You have {{.Count}} cakes.",    "other": "You have {{.Count}} cakes."  }}

active.ru.json

{  "greeting": {    "other": "Привет, {{.Name}}!"  },  "cakes_count": {    "one": "У вас {{.Count}} пирожное.",    "few": "У вас {{.Count}} пирожных.",    "many": "У вас {{.Count}} пирожных.",    "other": "У вас {{.Count}} пирожных."  }}

Note the use of pluralization rules: one, few, many, and other. In Russian, there are 4 forms, while in English there are only 2 (one/other). The library automatically selects the correct form based on the number.

Usage Example in Code

Now let's write code that loads translations and displays localized messages:

package main

import (    "fmt"    "log"

    "github.com/nicksnyder/go-i18n/v2/i18n"    "golang.org/x/text/language")

func main() {    // Create a bundle with language files    bundle := i18n.NewBundle(language.English)    bundle.RegisterUnmarshalFunc("json", json.Unmarshal)

    // Load translation files    _, err := bundle.LoadMessageFile("active.en.json")    if err != nil {        log.Fatal(err)    }    _, err = bundle.LoadMessageFile("active.ru.json")    if err != nil {        log.Fatal(err)    }

    // Create a localizer for the Russian language    localizer := i18n.NewLocalizer(bundle, "ru")

    // Example 1: Simple greeting    greeting, err := localizer.Localize(&i18n.LocalizeConfig{        MessageID: "greeting",        TemplateD