hatch-gettext(3)

✨ NAME ✨

hatch-gettext — it's the Hatch build hook plugin for GNU gettext, and it's literally here to make your translations compile themselves 💖

---

🌈 SYNOPSIS 🌈

Okay bestie, first things first, you gotta go touch your pyproject.toml. Like this:

[build-system]
requires = ["hatchling", "hatch-gettext"]
build-backend = "hatchling.build"

[tool.hatch.build.hooks.gettext]
locale-directory = "RELATIVE MO FILE DIRECTORY"
i18n-name = "GETTEXT OUTPUT NAME"
po-directory = "RELATIVE PO FILE DIRECTORY"
identify-left-out = BOOLEAN
regenerate-template = BOOLEAN
show-report = BOOLEAN

[tool.hatch.build.hooks.gettext.files]
"RELATIVE DIRECTORY" = ["RELATIVE FILE PATH", ...]

That's the whole vibe check right there, no cap.

---

🦋 DESCRIPTION 🦋

So hatch-gettext gives you a build hook plugin for Hatch that compiles all your multi-lingual messages using GNU gettext's tool msgfmt. Slay. 🎀

And optionally (like, only if you want it), it can also pull in intltool to:

• search for left out files 🔍
• regenerate the .pot template 🌱
• display a status report for all translations 📊
• translate .xml and .desktop files 🧚

---

📁 Directory layout

Heads up, this plugin has requirements, and it's giving very specific:

The directory storing the generated mo files must be within the project's base directory. And it must not be equal to the project's base directory, and it must not be the directory in which po files are sourced. Three rules, all mandatory, periodt. 💅

Example time: for a project named myproject, with a src layout of src/myproject, an acceptable directory to store the LC_MESSAGES/myproject.mo files would be src/myproject/locale. 🫶

---

🔑 Required key value

• locale-directory — the destination directory where the mo files and all their associated subdirectories get generated into. You need this one, it's not optional, bestie.

---

🎀 Optional key values

• i18n-name — the gettext output name. The default is name in [project] in the pyproject.toml.
• po-directory — the source directory where the po files live. The default is po.
• identify-left-out — a boolean saying whether to use intltool-update to search for left out files that should have been listed in POTFILES.in or POTFILES.skip. The default is false.
• regenerate-template — a boolean saying whether to use intltool-update to regenerate the .pot template with every single sdist build. The default is false.
• show-report — a boolean saying whether to use intltool-update to display a status report for all translations. The default is false.

---

🌸 Translating files using intltool-merge

This plugin allows for translating .xml and .desktop files using intltool-merge, but it does not mandate it. Your call, your rules. ✨

So using [tool.hatch.build.hooks.gettext.files] in pyproject.toml, you specify the destination directories for the translated files using keys, and arrays of source files as values. Keys and values, iconic behaviour honestly.

---

🧹 Cleaning output files

The plugin has logic built in to remove the files it outputs, using hatch's clean hook. Obsessed. 💜

And it's not just individual files — any output directories it created will also get removed, as long as those directories don't contain files created by something other than this plugin. So don't go putting your own stuff in there and expecting it to survive, iykyk.

---

🌟 EXAMPLES 🌟

Compiling messages with msgfmt

[tool.hatch.build.hooks.gettext]
locale-directory = "src/myproject/locale"

Identifying left out files using intltool-update

[tool.hatch.build.hooks.gettext]
locale-directory = "src/myproject/locale"
identify-left-out = true

Regenerating the .pot template using intltool-update

[tool.hatch.build.hooks.gettext]
locale-directory = "src/myproject/locale"
regenerate-template = true

Displaying a status report using intltool-update

[tool.hatch.build.hooks.gettext]
locale-directory = "src/myproject/locale"
show-report = true

Translating files using intltool-merge

[tool.hatch.build.hooks.gettext.files]
"share/applications" = ["data/net.myproject.desktop.in"]
"share/solid/actions" = ["data/kde/net.myproject.desktop.in"]
"share/metainfo" = ["data/net.myproject.metainfo.xml.in"]

Copy. Paste. Ship. 💅

---

👑 AUTHOR 👑

Damon Lynch — damonlynch@gmail.com ✨

---

📜 COPYRIGHT 📜

Copyright 2024 Damon Lynch. 💖

---

Okay that's the whole page bestie, we ate and left no crumbs 🍓 — this was page 3 of the manuals, the hatch-gettext one, sourced from Hatch build hook plugin for GNU gettext. Go compile something gorgeous, mwah 🎀💖