python-gettext

Common errors

• ModuleNotFoundError: No module named 'msgfmt_compiler'

  cause Attempting to import from the old module name (`msgfmt_compiler`) after upgrading to `python-gettext` version 5.0 or later.
  fix Change your import statement to `from gettext_compiler import compile_mo_file`.

• ModuleNotFoundError: No module named 'gettext_compiler'

  cause The `python-gettext` package is not installed in the current environment or the Python interpreter cannot find it.
  fix Install the package using `pip install python-gettext`. If in a virtual environment, ensure it's activated.

• FileNotFoundError: [Errno 2] No such file or directory: 'path/to/non_existent.po'

  cause The input `.po` file path provided to `compile_mo_file` does not exist or is incorrect.
  fix Verify that the path to your `.po` file is correct and the file exists at that location relative to your script's execution directory, or provide an absolute path.

• UnicodeDecodeError: 'utf-8' codec can't decode byte 0x... in position ...: invalid start byte

  cause The input `.po` file is not encoded in UTF-8, or contains invalid UTF-8 sequences, and the compiler is attempting to decode it as such.
  fix Ensure your `.po` file is correctly saved with UTF-8 encoding. If your `.po` file uses a different encoding, you may need to convert it to UTF-8 before processing.

Warnings

• breaking The primary import module name changed from `msgfmt_compiler` to `gettext_compiler` in version 5.0.
  Fix: Update your import statements from `from msgfmt_compiler import ...` to `from gettext_compiler import ...`.
• breaking Python 2 support was dropped in version 4.0. The library now requires Python 3.7 or newer.
  Fix: Ensure your project is running on Python 3.7+ to use `python-gettext` versions 4.0 and higher.
• gotcha This library (`python-gettext`) is for *compiling* `.po` files to `.mo` files. It is often confused with Python's built-in `gettext` module, which provides runtime translation APIs using already compiled `.mo` files.
  Fix: Remember that `python-gettext` provides the `gettext_compiler` module for the build-time step of creating `.mo` files, while the standard `gettext` module is used at runtime for actual message lookup.
• gotcha Incorrect encoding of `.po` files can lead to compilation errors or corrupted `.mo` files. The compiler defaults to UTF-8.
  Fix: Ensure your `.po` files are consistently encoded, preferably UTF-8. If using a different encoding, you may need to pre-process the `.po` content before passing it to the compiler.

Install

• pip install python-gettext Install latest version

Imports

• compile_mo_file
  wrong:

  from msgfmt_compiler import compile_mo_file

  correct:

  from gettext_compiler import compile_mo_file

  The primary module was renamed from 'msgfmt_compiler' to 'gettext_compiler' in version 5.0.

Quickstart

This quickstart demonstrates how to programmatically compile a `.po` file into a `.mo` file using `gettext_compiler.compile_mo_file`. It creates a simple dummy `.po` file, compiles it, and then cleans up the generated files.

import os
from gettext_compiler import compile_mo_file

# Create a dummy .po file for demonstration
po_content = '''
msgid ""
msgstr ""
"Project-Id-Version: Test Project\n"
"Language-Team: \n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: 8bit\n"

msgid "Hello, world!"
msgstr "Hola, mundo!"
'''

po_file_path = "example.po"
mo_file_path = "example.mo"

with open(po_file_path, "w", encoding="utf-8") as f:
    f.write(po_content)

# Compile the .po file to a .mo file
try:
    compile_mo_file(po_file_path, mo_file_path)
    print(f"Successfully compiled '{po_file_path}' to '{mo_file_path}'")
except Exception as e:
    print(f"Error compiling file: {e}")
finally:
    # Clean up the created files
    if os.path.exists(po_file_path):
        os.remove(po_file_path)
    if os.path.exists(mo_file_path):
        os.remove(mo_file_path)