hatch-msgfmt-s-ball

Automatically compile po files to mo ones at build time using msgfmt.py

Table of Contents

• Goal
• Current Status
• Usage
  • .po files
    • LANG folders organization
  • .mo files
  • Configuration
• Installation
  • Developer installation
• Contributing
• License

Goal

This package is a hatchling plugin that helps to automatically compile translation sources at build time. It internally uses a patched version of the msgfmt.py script from the Tools folder of the CPython source. Because of that it has no dependency and does not require any external tools.

Current Status

This package is released as Production/Stable. It has a test coverage above 90%. I currently use it for (the development version of) another project of mine i18nparse

Releases use a semantic major.minor.patch versioning. The full source code is available on GitHub.

Old Python versions support

Python 3.8 has reached its end of life, but it is still shipped in WSL. For that reason, it is no longer supported starting with the 1.1.0 version, but it is still supported in the 1.0.0 one. Major improvements or bug fixes should be implemented in the 1.0 branch.

Usage

As it is only a hatchling hook plugin, this package has no direct interface. It uses the Application object provided by hatchling for its messages, so it is possible to increase its verbosity when the behaviour is unexpected by just passing -v params to the hatch build command.

.po files

The source .po are expected to be in a folder under the root source directory. The default directory is messages but it can be changed through the configuration file. It can even be . if the files are directly in the root directory.

They are expected to be named LANG.po or domain-LANG.po. When no domain is present in the file name, the default domain is the last component of the source folder, or the package name if the source folder is . or messages.

LANG folders organization

Alternatively the source directory can contain LANG folders (e.g. fr_CA or es) that in turn contain domain.po files, possibly under a hierarchy of subfolders. The goal is to mimic a classical locale hierarchy: LANG/LC_MESSAGES/domain.po

It is even possible (but not recommended) to mix both organizations.

.mo files

For every .po file found, a corresponding compiled file is generated as locale/LANG/LC_MESSAGES/domain.mo under the project root directory. The default locale name can be changed through the builder configuration.

Configuration

The hatch-msgfmt-s-ball plugin can be configured as any other plugin through the pyproject.toml file. You must first declare it with:

[build-system]
requires = ["hatchling", "hatch-msgfmt-s-ball"]
build-backend = "hatchling.build"

Then you have to tell the builder that it must be called for the wheel target:

[tool.hatch.build.targets.wheel.hooks.msgfmt]

That section can be left empty if you accept the defaults. It is equivalent to:

[tool.hatch.build.targets.wheel.hooks.msgfmt]
locale = "locale"
messages = "messages"

In addition to the locale and messages options to respectively declare the source folder containing the po files and the generated locale folder, it is possible to declare a default domain with the domain directive:

[tool.hatch.build.targets.wheel.hooks.msgfmt]
domain = "my_app"
messages = "src"

As the messages folder is not named messages the default domain would have been src without the domain directive.

Installation

For normal usage, no installation is required. Any Python installer using the pyproject.toml file will be able to automatically download and install it at build time.

Developer installation

If you want to use the source of hatch-msgfmt-s-ball, you can download a source package form PyPI, or better clone it from GitHub:

git clone https://github.com/s-ball/hatch-msgfmt-s-ball.git

You will benefit from git for you own changes.

Contributing

As I am the only developer, I cannot guarantee very fast feedbacks. Anyway, I shall be glad to receive issues or pull requests on GitHUB.

License

hatch-msgfmt-s-ball is distributed under the terms of the MIT license.