goxgettext

gettext-style extraction workflow for Go and GoHTML projects
Extract translation keys, generate POT/PO catalogs, update language files from LINGUAS, and keep POTFILES in sync.

Install · Usage · Example · Release · License

Tip

Quick start:

goxgettext --all --output-dir po .

Lightweight gettext-style extractor for Go projects.

goxgettext scans Go source files and GoHTML/HTML templates, collects translatable strings, and generates POT/PO catalogs for your project.

✨ Features

• Extracts messages from Go calls such as gettext, t, T, and i18n
• Scans GoHTML and HTML templates for translation calls (keyword-based)
• Supports recursive directory scanning
• Generates POT and PO output
• Can create language-specific PO files and a POTFILES list from LINGUAS
• Supports custom keywords and additional file extensions

🚀 Installation

Install the latest release binary with Go:

go install github.com/gouef/goxgettext@latest

Install from the repository source:

make build

The binary will be created at ./bin/goxgettext and can be run directly.

Install from a single shell script:

curl -fsSL https://raw.githubusercontent.com/gouef/goxgettext/main/install.sh -o /tmp/install-goxgettext.sh
sh /tmp/install-goxgettext.sh

The script downloads the correct release binary for your platform and installs it to $HOME/.local/bin/goxgettext by default. Make sure that directory is on your PATH.

No chmod +x is required here — the script is intended to be run as sh /tmp/install-goxgettext.sh.

If you want a system-wide install, you can override the target directory:

INSTALL_DIR=/usr/local/bin sh /tmp/install-goxgettext.sh

After installation, you can run goxgettext directly from your shell.

🧪 Usage

The simplest workflow is to generate everything in one step:

./bin/goxgettext --all --output-dir locale .

Language files are generated from entries in LINGUAS (for example cs and en).

This creates:

• a POT file at locale/messages.pot
• a PO file at locale/messages.po
• language files such as locale/cs.po
• a locale/POTFILES list

If you only want a POT catalog:

./bin/goxgettext --output messages.pot .

If you only want a PO catalog:

./bin/goxgettext --format po --output messages.po .

If you want to generate language files without writing the POT/PO files:

./bin/goxgettext --output-dir locale .

This also uses LINGUAS to decide which language files are generated.

Create release binaries for multiple platforms:

make release

📘 Example

Minimal project input:

my-app/
  po/
    LINGUAS
  views/
    navigation.gohtml
  main.go

po/LINGUAS (one language per line):

cs
en

views/navigation.gohtml:

<nav>
  <a>{{ i18n "nav.home" }}</a>
  <a>{{ i18n "nav.projects" }}</a>
</nav>

Run:

goxgettext --all --output-dir po .

Generated files:

po/messages.pot
po/messages.po
po/cs.po
po/en.po
po/POTFILES

po/messages.pot contains references with line numbers, for example:

#: /path/to/my-app/views/navigation.gohtml:2
msgid "nav.home"
msgstr ""

📦 Release binaries

When a tag matching v* is pushed, the GitHub Actions workflow in .github/workflows/release.yml builds release artifacts for Linux, macOS, and Windows and uploads them to the GitHub Release.

You can also trigger the workflow manually from the Actions tab and choose a tag name.

Download the appropriate binary for your platform from the release page and run it directly.

⚙️ Useful flags

• --output: write the generated catalog to a file
• --format: select pot or po output
• --keyword: add custom translation function names
• --extension: include additional file extensions to scan
• --output-dir: write generated language files to a directory
• LINGUAS: language list file used for generating/updating language catalogs

🛠️ Development

Run the test suite:

make test

Generate a coverage report:

make coverage

Contributors

🤝 Contributing

See CONTRIBUTING.md.

License

This project is licensed under the Apache License 2.0. See LICENSE for details.