Gotext

GNU gettext utilities for Go.

gotext is a native Go implementation of the GNU Gettext utilities. It provides a thread-safe, flexible, and powerful way to handle internationalization (i18n) and localization (l10n) in your Go applications.

---

📖 Read the Full Documentation

---

Table of Contents

• Features
• Installation
• Getting Started
• CLI Tool (xgotext)
• Advanced Usage
  • Locale Object
  • Plural Forms
  • Dynamic Variables
• Directory Structure
• Contributing
• License

---

Features

• Native Go implementation of Gettext (the core library has no external dependencies).
• Full support for PO and MO files.
• Pluralization rules support via GNU Gettext plural-form expressions.
• Message context support (msgctxt).
• Thread-safe for concurrent use.
• Works with UTF-8 by default.
• Integrated CLI tool (xgotext) for string extraction.
• Serializable objects for caching.
• Plain-string results that plug directly into Go's text/template and html/template pipelines.

---

Installation

go get github.com/leonelquinteros/gotext

---

Getting Started

For a quick start, use the package-level API:

package main

import (
    "fmt"
    "github.com/leonelquinteros/gotext"
)

func main() {
    // Configure package: locales path, language, and domain
    gotext.Configure("/path/to/locales", "en_US", "default")

    // Simple translation
    fmt.Println(gotext.Get("Hello, world!"))

    // Translation with variables
    fmt.Println(gotext.Get("Hello, %s!", "Gopher"))
}

For more details, see the Getting Started Guide.

---

CLI Tool (xgotext)

gotext includes a command-line tool to extract translatable strings from your Go source code.

Install xgotext:

go install github.com/leonelquinteros/gotext/cli/xgotext@latest

Extract strings:

xgotext -in . -out locales/templates

The command generates .pot templates under locales/templates; merge those templates into language-specific .po files.

See the xgotext Documentation for full usage details.

---

Advanced Usage

Using Locale object

For managing multiple languages or domains independently:

l := gotext.NewLocale("/path/to/locales", "es_UY")
l.AddDomain("default")
fmt.Println(l.Get("Translate this"))

Use plural forms of translations

gotext handles complex pluralization rules defined in PO headers:

// GetN(singular, plural, quantity, args...)
fmt.Println(gotext.GetN("I have one apple.", "I have %d apples.", 5, 5))

See the Plural Forms Guide for more examples.

Using dynamic variables on translations

Supports standard fmt package syntax:

name := "John"
fmt.Println(gotext.Get("Hi, my name is %s", name))

More advanced scenarios

• Embedded translation files (embed.FS) and named %(name)s formatting: see the Advanced Usage Guide.
• Languages fallback: pass multiple languages to Configure as a colon-separated list (gotext.Configure("/path/to/locales", "es_UY:es:en_US", "default")).
• Serialization/caching of parsed locales: Locale.MarshalBinary / UnmarshalBinary.

---

Locales directories structure

The package expects a standard Gettext directory structure:

/path/to/locales
  /en_US
    /LC_MESSAGES
      default.po
  /es_ES
    /LC_MESSAGES
      default.po

Translation files can live either inside an LC_MESSAGES subdirectory or directly under the language code (/es_ES/default.po); both layouts are supported.

It supports automatic language simplification (e.g., falling back from en_UK to en).

---

Contributing

We welcome contributions of all kinds!

• Contributing Guidelines
• Code of Conduct

---

License

gotext is released under the MIT License.