Skip to main content

Guía completa de internacionalización en Go

De los archivos de mensajes a una resolución regional segura entre goroutines: configure i18n en su aplicación Go con go-i18n y automatice después las traducciones con IA.

1

Instalar go-i18n

go-i18n es la biblioteca de internacionalización más popular para Go. Utiliza reglas de plural CLDR, plantillas de Go para interpolar variables y admite archivos de mensajes JSON, TOML y YAML. También necesita golang.org/x/text para asociar etiquetas de idioma.

go-i18n v2 requiere Go 1.16 o posterior. El paquete golang.org/x/text analiza y asocia etiquetas de idioma BCP 47, que go-i18n utiliza internamente para seleccionar las reglas de plural.
Terminal
go get -u github.com/nicksnyder/go-i18n/v2/i18n
go get -u golang.org/x/text/language
2

Crear archivos de mensajes

Cree un archivo JSON por idioma dentro de un directorio locales. Cada mensaje tiene un identificador y una o varias formas plurales. Go-i18n utiliza la sintaxis de plantillas de Go —llaves dobles con prefijo de punto— para interpolar variables.

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."
  }
}
Utilice identificadores descriptivos como 'ItemCount' o 'WelcomeBack' en vez de rutas separadas por puntos. go-i18n utiliza identificadores planos, no claves anidadas. Manténgalos en PascalCase conforme a las convenciones de Go.
3

Cargar el Bundle

Bundle es el registro central de go-i18n. Créelo al iniciar, registre el formato y cargue todos los archivos. Es seguro entre goroutines: créelo una vez y compártalo en toda la aplicación.

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) // "こんにちは、世界！"
}
Si ve 'message not found', compruebe tres cosas: 1) que el archivo se cargara mediante LoadMessageFile o MustLoadMessageFile; 2) que la extensión coincida con la función de deserialización registrada; 3) que MessageID en LocalizeConfig coincida exactamente —incluidas mayúsculas y minúsculas— con la clave del JSON.
4

Utilizar Localizer

Cree un Localizer por solicitud con el idioma preferido del usuario. Resuelve mensajes desde Bundle, renderiza plantillas con text/template de Go y selecciona la forma correcta según 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 acepta varias cadenas de idioma y las prueba por orden. Pase directamente Accept-Language: i18n.NewLocalizer(bundle, r.Header.Get("Accept-Language")). go-i18n analiza el encabezado y busca automáticamente entre las traducciones disponibles.
5

Gestionar reglas de plural

go-i18n implementa reglas CLDR para todos los idiomas. El inglés tiene 2 formas (one y other), el árabe 6 (zero, one, two, few, many y other) y el japonés 1 (other). Defina todas las necesarias en los archivos y go-i18n seleccionará la correcta según 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 y TemplateData son independientes. PluralCount selecciona la forma y TemplateData proporciona valores para renderizar. Si necesita el número en el texto, páselo en ambos: PluralCount: n y TemplateData: map[string]interface{'}'{"Count": n}.
6

Detección de configuración regional

En aplicaciones web, detecte el idioma preferido mediante parámetros de consulta, cookies, Accept-Language o segmentos de ruta. Utilice language.Matcher de golang.org/x/text para negociar el idioma conforme a 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 devuelve la mejor coincidencia entre sus idiomas admitidos, no la preferencia sin procesar. Si un usuario solicita 'pt-BR' y solo admite 'pt', devuelve correctamente 'pt'. Sin matcher, tendría que crear lógica de respaldo manual para cada variante.
7

Corregir el respaldo por clave con go-locale-chain

go-i18n tiene una limitación conocida: cuando coincide una configuración —hay alguna traducción cargada—, las claves ausentes no pasan a la siguiente. Un usuario pt-BR con un archivo parcial recibe cadenas vacías en vez de pt-PT o pt. go-locale-chain lo corrige mediante resolución por clave en 75 cadenas 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 es un paquete Go de código abierto sin dependencias externas. Complementa go-i18n: use este último para cargar mensajes, pluralizar y renderizar plantillas, y go-locale-chain para resolver correctamente las cadenas de respaldo.
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
Utilice ConfigureWithOverrides() para personalizar cadenas concretas y conservar las predeterminadas. Por ejemplo, simplifique pt-BR para que solo recurra a pt o añada una cadena ausente como sv-FI -> sv.
8

Automatizar traducciones

Cuando termine de configurar i18n, traduzca los archivos de configuración regional con IA. Genere todos los idiomas de destino a partir del archivo de origen en inglés, directamente desde el IDE o en su canalización 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
Traduzca de forma incremental: cuando añada identificadores nuevos al archivo de origen, traduzca solo esas claves en vez de volver a generar todos los archivos. Así conserva las traducciones revisadas por personas.

Automatizar la calidad de la traducción

Detecte las claves ausentes y los marcadores rotos antes de publicar con i18n-validate. Pruebe la interfaz con pseudotraducciones mediante i18n-pseudo antes de recibir las reales.

Errores habituales

Discrepancia entre PluralCount y TemplateData

PluralCount selecciona la forma plural, pero no inyecta el valor en la plantilla. También debe pasar el número en TemplateData para que aparezca. Sin TemplateData, '{'{.Count}'}' renderiza '<no value>'.

Falta RegisterUnmarshalFunc

LoadMessageFile no devuelve ningún mensaje si olvida llamar a bundle.RegisterUnmarshalFunc() para el formato. Registre siempre json.Unmarshal —o toml/yaml— antes de cargar archivos.

El respaldo por clave no funciona

NewLocalizer de go-i18n acepta varios idiomas, pero cuando una configuración regional coincide con una sola clave, las ausentes devuelven cadenas vacías en vez de recurrir a la siguiente. Utilice go-locale-chain para añadir una cascada correcta por clave.

Sintaxis de plantilla: {'{.Var}'}, no {'{Var}'}

go-i18n utiliza la sintaxis text/template de Go. Las variables deben llevar un punto: {'{.Name}'}, no {'{Name}'}. El punto hace referencia al mapa TemplateData. Omitirlo provoca un error al ejecutar la plantilla.

Estructura de archivos 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

También puede traducir:

Pruebe i18n Agent ahora

Arrastre y suelte aquí su archivo de traducción

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

o haga clic para seleccionar

Idiomas de destino

No es necesario registrarsePresupuesto al instante

Respaldo de configuraciones regionales con go-locale-chain

Cuando falta una clave en una configuración regional como pt-BR, go-i18n pasa directamente al idioma predeterminado en vez de comprobar primero la configuración regional 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 nuestra guía de respaldo de configuraciones regionales para ver todos los frameworks admitidos y las 75 cadenas integradas. Learn more →

Preguntas frecuentes sobre i18n en Go