Skip to main content

O guia completo da internacionalização em Go

Dos arquivos de mensagens à resolução regional segura entre goroutines: configure i18n na sua aplicação Go com go-i18n e automatize as traduções com IA.

1

Instalar go-i18n

go-i18n é a biblioteca de internacionalização mais popular para Go. Utiliza regras de plural CLDR, modelos Go na interpolação de variáveis e aceita arquivos JSON, TOML e YAML. Também precisa de golang.org/x/text para corresponder etiquetas linguísticas.

go-i18n v2 exige Go 1.16 ou posterior. O pacote golang.org/x/text analisa e corresponde etiquetas BCP 47, que go-i18n utiliza internamente para selecionar regras de plural.
Terminal
go get -u github.com/nicksnyder/go-i18n/v2/i18n
go get -u golang.org/x/text/language
2

Criar arquivos de mensagens

Crie um arquivo JSON por idioma em um diretório locales. Cada mensagem tem um ID e uma ou mais formas plurais. Go-i18n utiliza sintaxe de modelos Go —chavetas duplas com prefixo de ponto— para interpolar variáveis.

locales/en.json
{
  "HelloWorld": { "other": "Hello, World!" },
  "Greeting": { "other": "Hello, {{.Name}}!" },
  "ItemCount": {
    "one": "{{.Count}} item",
    "other": "{{.Count}} items"
  },
  "WelcomeBack": {
    "other": "Welcome back, {{.Name}}. You have {{.Count}} messages."
  }
}
Utilize ID descritivos, como 'ItemCount' ou 'WelcomeBack', em vez de caminhos separados por pontos. go-i18n utiliza ID simples, não chaves aninhadas. Mantenha-os em PascalCase segundo as convenções Go.
3

Carregar o Bundle

Bundle é o registro central de go-i18n. Crie-o no início, registre o formato e carregue todos os arquivos. Bundle é seguro entre goroutines: crie-o uma vez e compartilhe-o em toda a aplicação.

main.go
package main

import (
    "encoding/json"
    "fmt"
    "github.com/nicksnyder/go-i18n/v2/i18n"
    "golang.org/x/text/language"
)

func main() {
    // 1. Create a bundle with a default language
    bundle := i18n.NewBundle(language.English)
    // 2. Register the unmarshal function for your file format
    bundle.RegisterUnmarshalFunc("json", json.Unmarshal)
    // 3. Load message files
    bundle.MustLoadMessageFile("locales/en.json")
    bundle.MustLoadMessageFile("locales/ja.json")
    bundle.MustLoadMessageFile("locales/de.json")
    // 4. Create a localizer and localize a message
    localizer := i18n.NewLocalizer(bundle, "ja")
    msg := localizer.MustLocalize(&i18n.LocalizeConfig{
        MessageID: "HelloWorld",
    })
    fmt.Println(msg) // "こんにちは、世界！"
}
Se vir 'message not found', verifique: 1) se o arquivo foi carregado com LoadMessageFile ou MustLoadMessageFile; 2) se a extensão corresponde à função de análise registrada; 3) se MessageID em LocalizeConfig corresponde exatamente à chave no JSON —incluindo maiúsculas e minúsculas—.
4

Utilizar o Localizer

Crie um Localizer para cada requisição com o idioma preferido do usuário. Localizer resolve mensagens de Bundle, apresenta modelos com o motor text/template de Go e seleciona a forma plural correta com base em PluralCount.

Using the Localizer
// Simple message
msg := localizer.MustLocalize(&i18n.LocalizeConfig{
    MessageID: "HelloWorld",
})

// Message with template data
msg := localizer.MustLocalize(&i18n.LocalizeConfig{
    MessageID: "Greeting",
    TemplateData: map[string]interface{}{
        "Name": "Alice",
    },
})
// "Hello, Alice!" (en) or "こんにちは、Aliceさん！" (ja)

// Plural + template data
msg := localizer.MustLocalize(&i18n.LocalizeConfig{
    MessageID: "ItemCount",
    PluralCount: 5,
    TemplateData: map[string]interface{}{
        "Count": 5,
    },
})
// "5 items" (en) or "5個のアイテム" (ja)

// Combined: plurals + multiple variables
msg := localizer.MustLocalize(&i18n.LocalizeConfig{
    MessageID: "WelcomeBack",
    TemplateData: map[string]interface{}{
        "Name":  "Alice",
        "Count": 3,
    },
})
HTTP handler with locale detection
func handler(w http.ResponseWriter, r *http.Request) {
    // Accept-Language: ja,en;q=0.9,de;q=0.8
    accept := r.Header.Get("Accept-Language")

    // NewLocalizer accepts multiple languages — first match wins
    localizer := i18n.NewLocalizer(bundle, accept)

    msg := localizer.MustLocalize(&i18n.LocalizeConfig{
        MessageID: "HelloWorld",
    })

    w.Header().Set("Content-Type", "text/plain; charset=utf-8")
    w.Write([]byte(msg))
}
NewLocalizer aceita várias strings de idioma e as tenta por ordem. Passe diretamente o cabeçalho Accept-Language: i18n.NewLocalizer(bundle, r.Header.Get("Accept-Language")). go-i18n o analisa e encontra automaticamente a tradução disponível.
5

Tratar regras de plural

go-i18n implementa regras CLDR para todos os idiomas. O inglês tem 2 formas —one e other—, o árabe 6 —zero, one, two, few, many e other— e o japonês 1 —other—. Defina todas as necessárias e go-i18n seleciona a correta com PluralCount.

Plural forms by language
// English: 2 forms (one, other)
{
  "ItemCount": {
    "one": "{{.Count}} item",
    "other": "{{.Count}} items"
  }
}

// Arabic: 6 forms (zero, one, two, few, many, other)
{
  "ItemCount": {
    "zero": "لا عناصر",
    "one": "عنصر واحد",
    "two": "عنصران",
    "few": "{{.Count}} عناصر",
    "many": "{{.Count}} عنصرًا",
    "other": "{{.Count}} عنصر"
  }
}

// Japanese: 1 form (other)
{
  "ItemCount": {
    "other": "{{.Count}}個のアイテム"
  }
}
Using plural rules
// go-i18n selects the correct plural form based on PluralCount
localizer := i18n.NewLocalizer(bundle, "ar")

msg := localizer.MustLocalize(&i18n.LocalizeConfig{
    MessageID:   "ItemCount",
    PluralCount: 3,
    TemplateData: map[string]interface{}{
        "Count": 3,
    },
})
// Arabic "few" form: "3 عناصر"

msg = localizer.MustLocalize(&i18n.LocalizeConfig{
    MessageID:   "ItemCount",
    PluralCount: 1,
    TemplateData: map[string]interface{}{
        "Count": 1,
    },
})
// Arabic "one" form: "عنصر واحد"
PluralCount e TemplateData são separados. PluralCount seleciona a forma e TemplateData fornece valores ao modelo. Se precisar do número no texto, passe-o em ambos: PluralCount: n e TemplateData: map[string]interface{'}'{"Count": n}.
6

Detecção regional

Nas aplicações Web, detecte o idioma preferido em várias fontes: parâmetros da consulta, cookies, Accept-Language ou segmentos do caminho. Utilize golang.org/x/text/language.Matcher para negociação linguística compatível com BCP 47.

Locale detection middleware
// detectLocale resolves the user's preferred language.
// Priority: query param > cookie > Accept-Language header > default
func detectLocale(r *http.Request, matcher language.Matcher) string {
    // 1. Explicit query parameter: ?lang=ja
    if lang := r.URL.Query().Get("lang"); lang != "" {
        tag, _, _ := matcher.Match(language.Make(lang))
        return tag.String()
    }
    // 2. Cookie from previous selection
    if cookie, err := r.Cookie("lang"); err == nil {
        tag, _, _ := matcher.Match(language.Make(cookie.Value))
        return tag.String()
    }
    // 3. Accept-Language header
    accept := r.Header.Get("Accept-Language")
    if accept != "" {
        tags, _, _ := language.ParseAcceptLanguage(accept)
        if len(tags) > 0 {
            tag, _, _ := matcher.Match(tags...)
            return tag.String()
        }
    }
    return "en" // 4. Default
}

// Usage:
matcher := language.NewMatcher([]language.Tag{
    language.English, language.Japanese,
    language.German, language.Spanish,
})

http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
    locale := detectLocale(r, matcher)
    localizer := i18n.NewLocalizer(bundle, locale)
    // ... use localizer
})
language.NewMatcher devolve a melhor correspondência entre os idiomas compatíveis, não a preferência em bruto. Se o usuário pedir 'pt-BR' e só aceitar 'pt', devolve corretamente 'pt'. Sem matcher, precisaria de lógica manual para todas as variantes.
7

Corrigir o fallback por chave com go-locale-chain

go-i18n tem uma limitação conhecida: quando uma localidade corresponde —tem alguma tradução carregada—, as chaves ausentes não avançam para a localidade seguinte. Um usuário pt-BR com um arquivo parcial recebe strings vazias em vez de pt-PT ou pt. go-locale-chain corrige isso por chave em 75 cadeias integradas.

Terminal
go get github.com/i18n-agent/go-locale-chain
go-locale-chain with go-i18n
package main

import (
    "encoding/json"
    "fmt"

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

func main() {
    // 1. Configure fallback chains (call once at startup)
    localechain.Configure()

    // 2. Set up go-i18n bundle as usual
    bundle := i18n.NewBundle(language.English)
    bundle.RegisterUnmarshalFunc("json", json.Unmarshal)
    bundle.MustLoadMessageFile("locales/en.json")
    bundle.MustLoadMessageFile("locales/pt.json")
    bundle.MustLoadMessageFile("locales/pt-PT.json")
    bundle.MustLoadMessageFile("locales/pt-BR.json")

    // 3. Resolve with per-key fallback
    result, _ := localechain.ResolveWithLoader("pt-BR", func(locale string) (map[string]string, error) {
        localizer := i18n.NewLocalizer(bundle, locale)
        messages := make(map[string]string)
        for _, id := range []string{"hello", "goodbye", "thanks"} {
            msg, err := localizer.Localize(&i18n.LocalizeConfig{MessageID: id})
            if err == nil {
                messages[id] = msg
            }
        }
        return messages, nil
    })

    fmt.Println(result["hello"])   // "Olá (BR)"   — from pt-BR
    fmt.Println(result["goodbye"]) // "Adeus (PT)" — fallback to pt-PT
    fmt.Println(result["thanks"])  // "Obrigado"   — fallback to pt
}
go-locale-chain é um pacote Go de código aberto sem dependências externas. Complementa go-i18n: utilize go-i18n para carregar mensagens, pluralizar e apresentar modelos e go-locale-chain para resolver devidamente as cadeias de fallback.
Standalone usage (no go-i18n)
// Standalone: zero external dependencies, works with any format
localechain.Configure()

result, _ := localechain.ResolveWithLoader("es-MX", func(locale string) (map[string]string, error) {
    data, err := os.ReadFile(fmt.Sprintf("locales/%s.json", locale))
    if err != nil {
        return nil, err // Locale file doesn't exist — skip
    }
    var msgs map[string]string
    json.Unmarshal(data, &msgs)
    return msgs, nil
})
// es-MX -> es-419 -> es: each key resolved from most specific locale
Utilize ConfigureWithOverrides() para personalizar cadeias mantendo as predefinições. Por exemplo, simplifique pt-BR para recorrer apenas a pt ou adicione sv-FI -> sv.
8

Automatizar as traduções

Depois de concluir a configuração de i18n, traduza os arquivos de localidade com IA. Gere traduções para todos os idiomas de destino a partir do arquivo inglês, diretamente no IDE ou pipeline de CI/CD.

Terminal
# In your IDE, ask your AI assistant:
> Translate locales/en.json to German, Japanese, and Spanish

✓ locales/de.json created (1.2s)
✓ locales/ja.json created (1.5s)
✓ locales/es.json created (1.1s)

# Or use the CLI in CI/CD:
npx i18n-agent translate locales/en.json --lang de,ja,es
Traduza de forma incremental: quando adicionar novos ID ao arquivo de origem, traduza apenas as novas chaves em vez de voltar a gerar tudo. Assim preserva traduções revisadas por pessoas.

Automatizar a qualidade das traduções

Detecte chaves em falta e marcadores danificados antes da publicação com i18n-validate. Teste a interface com pseudotraduções através de i18n-pseudo antes de chegarem as traduções reais.

Erros frequentes

Incompatibilidade entre PluralCount e TemplateData

PluralCount seleciona a forma plural, mas não injeta o valor no modelo. Deve passar também o número em TemplateData para aparecer na mensagem. Sem TemplateData, '{'{.Count}'}' é apresentado como '<no value>'.

RegisterUnmarshalFunc em falta

LoadMessageFile devolve silenciosamente zero mensagens se você esquecer de chamar bundle.RegisterUnmarshalFunc() para o formato. Registre sempre json.Unmarshal —ou toml/yaml— antes de carregar arquivos.

O fallback por chave não funciona

NewLocalizer de go-i18n aceita vários idiomas, mas, quando uma localidade corresponde a uma chave, as demais chaves ausentes retornam strings vazias em vez de recorrer ao fallback. Utilize go-locale-chain para obter uma cascata correta por chave.

Sintaxe dos modelos: {'{.Var}'}, não {'{Var}'}

go-i18n utiliza a sintaxe text/template de Go. As variáveis devem começar por um ponto: {'{.Name}'}, não {'{Name}'}. O ponto se refere ao mapa TemplateData. Omiti-lo provoca um erro de execução do modelo.

Estrutura de arquivos recomendada

Project Structure
my-go-app/
├── locales/
│   ├── en.json           # Source language (English)
│   ├── de.json           # German translations
│   ├── ja.json           # Japanese translations
│   ├── es.json           # Spanish translations
│   ├── pt.json           # Portuguese (base)
│   ├── pt-PT.json        # Portuguese (Portugal)
│   └── pt-BR.json        # Portuguese (Brazil)
├── i18n/
│   ├── bundle.go         # Bundle initialization
│   ├── detect.go         # Locale detection logic
│   └── middleware.go      # HTTP middleware for locale
├── main.go
├── go.mod
└── go.sum

Também pode traduzir:

Experimente já o i18n Agent

Solte aqui seu arquivo de tradução

JSON, YAML, PO, XML, CSV, Markdown, Properties

ou clique para selecionar

Idiomas de destino

Sem cadastroEstimativa imediata

Fallback regional com go-locale-chain

Quando falta uma chave em uma localidade como pt-BR, go-i18n passa diretamente para o idioma predefinido em vez de verificar primeiro a localidade principal pt.

Terminal
go get github.com/i18n-agent/go-locale-chain
Configuration
import localechain "github.com/i18n-agent/go-locale-chain"

chain := localechain.New(localechain.Config{
    Fallbacks: map[string][]string{
        "pt-BR":      {"pt", "en"},
        "zh-Hant-HK": {"zh-Hant", "zh", "en"},
    },
})

Consulte nosso guia de fallback regional para ver a lista completa de frameworks compatíveis e as 75 cadeias integradas. Learn more →

Perguntas frequentes sobre i18n em Go