0
# polib
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: polib
7
- **Language**: Python
8
- **Installation**: `pip install polib`
9
- **Version**: 1.2.0
10
- **License**: MIT
11

12
## Core Imports
13

14
```python
15
import polib
16
```
17

18
## Basic Usage
19

20
```python
21
import polib
22

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

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

31
# Find a specific entry
32
entry = po.find('Hello World')
33
if entry:
34
    entry.msgstr = 'Hola Mundo'
35

36
# Add a new entry
37
new_entry = polib.POEntry(
38
    msgid='Welcome',
39
    msgstr='Bienvenido',
40
    occurrences=[('views.py', 42)]
41
)
42
po.append(new_entry)
43

44
# Save the file
45
po.save()
46

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

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

53
# Convert MO to PO
54
mo.save_as_pofile('recovered.po')
55
```
56

57
## Architecture
58

59
polib uses a simple and intuitive object model:
60

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

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

68
## Capabilities
69

70
### File Operations
71

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

74
```python { .api }
75
def pofile(pofile, **kwargs): ...
76
def mofile(mofile, **kwargs): ...
77
```
78

79
```python { .api }
80
class POFile(list):
81
    def save(self, fpath=None, repr_method='__unicode__', newline=None): ...
82
    def save_as_mofile(self, fpath): ...
83

84
class MOFile(list):
85
    def save(self, fpath=None): ...
86
    def save_as_pofile(self, fpath): ...
87
```
88

89
[File Operations](./file-operations.md)
90

91
### Entry Manipulation
92

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

95
```python { .api }
96
class POEntry:
97
    def __init__(self, msgid='', msgstr='', **kwargs): ...
98
    def translated(self): ...
99

100
class MOEntry:
101
    def __init__(self, msgid='', msgstr='', **kwargs): ...
102
```
103

104
```python { .api }
105
class POFile(list):
106
    def find(self, st, by='msgid', include_obsolete_entries=False, msgctxt=False): ...
107
    def append(self, entry): ...
108
    def percent_translated(self): ...
109
    def translated_entries(self): ...
110
    def untranslated_entries(self): ...
111
    def fuzzy_entries(self): ...
112
```
113

114
[Entry Manipulation](./entry-manipulation.md)
115

116
### Utility Functions
117

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

120
```python { .api }
121
def detect_encoding(file, binary_mode=False): ...
122
def escape(st): ...
123
def unescape(st): ...
124
```
125

126
[Utilities](./utilities.md)
127

128
## Types
129

130
```python { .api }
131
# Module constants
132
default_encoding: str  # Default encoding ('utf-8') when detection fails
133

134
# Entry attributes and properties
135
class POEntry:
136
    msgid: str              # Source message ID
137
    msgstr: str             # Translated message
138
    msgid_plural: str       # Plural source message
139
    msgstr_plural: dict     # Plural translations {0: str, 1: str, ...}
140
    msgctxt: str            # Message context
141
    comment: str            # Generated comment
142
    tcomment: str           # Translator comment
143
    occurrences: list       # List of (filename, line_number) tuples
144
    flags: list             # List of flags (e.g., ['fuzzy', 'python-format'])
145
    previous_msgctxt: str   # Previous context (for fuzzy entries)
146
    previous_msgid: str     # Previous msgid (for fuzzy entries)
147
    previous_msgid_plural: str  # Previous msgid_plural (for fuzzy entries)
148
    obsolete: bool          # Whether entry is obsolete
149
    encoding: str           # Entry encoding
150
    fuzzy: bool            # Property: whether entry is fuzzy
151

152
class MOEntry:
153
    msgid: str              # Source message ID  
154
    msgstr: str             # Translated message
155
    msgid_plural: str       # Plural source message
156
    msgstr_plural: dict     # Plural translations {0: str, 1: str, ...}
157
    msgctxt: str            # Message context
158
    obsolete: bool          # Whether entry is obsolete
159
    encoding: str           # Entry encoding
160

161
# File attributes and properties
162
class POFile(list):
163
    fpath: str                    # File path
164
    wrapwidth: int               # Line wrap width (default 78)
165
    encoding: str                # File encoding
166
    check_for_duplicates: bool   # Whether to check for duplicates
167
    header: str                  # File header
168
    metadata: dict               # Metadata dictionary
169
    metadata_is_fuzzy: bool      # Whether metadata is fuzzy
170

171
class MOFile(list):
172
    fpath: str           # File path
173
    wrapwidth: int       # Line wrap width
174
    encoding: str        # File encoding
175
    magic_number: int    # MO file magic number
176
    version: int         # MO file version
177
```