or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

entry-manipulation.mdfile-operations.mdindex.mdutilities.md
tile.json

tessl/pypi-polib

A library to manipulate gettext files (po and mo files).

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/polib@1.2.x

To install, run

npx @tessl/cli install tessl/pypi-polib@1.2.0

index.mddocs/

polib

A comprehensive Python library for manipulating gettext files (po and mo files). polib provides complete functionality for loading, creating, modifying, and saving translation files used in software internationalization workflows, making it an essential tool for developers working with multilingual applications.

Package Information

  • Package Name: polib
  • Language: Python
  • Installation: pip install polib
  • Version: 1.2.0
  • License: MIT

Core Imports

import polib

Basic Usage

import polib

# Load a PO file
po = polib.pofile('messages.po')

# Iterate through translation entries
for entry in po:
    print(f"Original: {entry.msgid}")
    print(f"Translation: {entry.msgstr}")

# Find a specific entry
entry = po.find('Hello World')
if entry:
    entry.msgstr = 'Hola Mundo'

# Add a new entry
new_entry = polib.POEntry(
    msgid='Welcome',
    msgstr='Bienvenido',
    occurrences=[('views.py', 42)]
)
po.append(new_entry)

# Save the file
po.save()

# Convert PO to MO
po.save_as_mofile('messages.mo')

# Load an MO file
mo = polib.mofile('messages.mo')

# Convert MO to PO
mo.save_as_pofile('recovered.po')

Architecture

polib uses a simple and intuitive object model:

  • POFile/MOFile: Container classes that behave like Python lists, holding translation entries
  • POEntry/MOEntry: Individual translation entries containing source text, translations, and metadata
  • File Format Support: Complete support for PO, POT, and MO file formats with proper encoding detection
  • Metadata Management: Full support for file headers, translator comments, and entry-level metadata

This design provides both high-level convenience functions for common operations and low-level access to all gettext file format features.

Capabilities

File Operations

Load PO/POT files, MO files, and convert between formats. Includes automatic encoding detection and complete file format support.

def pofile(pofile, **kwargs): ...
def mofile(mofile, **kwargs): ...
class POFile(list):
    def save(self, fpath=None, repr_method='__unicode__', newline=None): ...
    def save_as_mofile(self, fpath): ...

class MOFile(list):
    def save(self, fpath=None): ...
    def save_as_pofile(self, fpath): ...

File Operations

Entry Manipulation

Create, modify, find, and manage translation entries with full support for pluralization, context strings, comments, and metadata.

class POEntry:
    def __init__(self, msgid='', msgstr='', **kwargs): ...
    def translated(self): ...

class MOEntry:
    def __init__(self, msgid='', msgstr='', **kwargs): ...
class POFile(list):
    def find(self, st, by='msgid', include_obsolete_entries=False, msgctxt=False): ...
    def append(self, entry): ...
    def percent_translated(self): ...
    def translated_entries(self): ...
    def untranslated_entries(self): ...
    def fuzzy_entries(self): ...

Entry Manipulation

Utility Functions

Encoding detection and string escaping utilities for working with gettext file formats.

def detect_encoding(file, binary_mode=False): ...
def escape(st): ...
def unescape(st): ...

Utilities

Types

# Module constants
default_encoding: str  # Default encoding ('utf-8') when detection fails

# Entry attributes and properties
class POEntry:
    msgid: str              # Source message ID
    msgstr: str             # Translated message
    msgid_plural: str       # Plural source message
    msgstr_plural: dict     # Plural translations {0: str, 1: str, ...}
    msgctxt: str            # Message context
    comment: str            # Generated comment
    tcomment: str           # Translator comment
    occurrences: list       # List of (filename, line_number) tuples
    flags: list             # List of flags (e.g., ['fuzzy', 'python-format'])
    previous_msgctxt: str   # Previous context (for fuzzy entries)
    previous_msgid: str     # Previous msgid (for fuzzy entries)
    previous_msgid_plural: str  # Previous msgid_plural (for fuzzy entries)
    obsolete: bool          # Whether entry is obsolete
    encoding: str           # Entry encoding
    fuzzy: bool            # Property: whether entry is fuzzy

class MOEntry:
    msgid: str              # Source message ID  
    msgstr: str             # Translated message
    msgid_plural: str       # Plural source message
    msgstr_plural: dict     # Plural translations {0: str, 1: str, ...}
    msgctxt: str            # Message context
    obsolete: bool          # Whether entry is obsolete
    encoding: str           # Entry encoding

# File attributes and properties
class POFile(list):
    fpath: str                    # File path
    wrapwidth: int               # Line wrap width (default 78)
    encoding: str                # File encoding
    check_for_duplicates: bool   # Whether to check for duplicates
    header: str                  # File header
    metadata: dict               # Metadata dictionary
    metadata_is_fuzzy: bool      # Whether metadata is fuzzy

class MOFile(list):
    fpath: str           # File path
    wrapwidth: int       # Line wrap width
    encoding: str        # File encoding
    magic_number: int    # MO file magic number
    version: int         # MO file version