Welcome to polib’s documentation!¶
This documentation covers the latest release of polib.
polib is a library to manipulate, create, modify gettext files (pot, po and mo files). You can load existing files, iterate through it’s entries, add, modify entries, comments or metadata, etc. or create new po files from scratch.
polib supports out of the box any version of python ranging from 2.4 to latest 3.X version.
polib is pretty stable now and is used by many opensource projects.
polib is completely free and opensource, the license used is the MIT license. It was developed back in 2006 by David Jean Louis and it is still actively maintained.
To get up and running quickly, consult the quick-start guide, which describes all the necessary steps to install and use polib. For more detailed information about how to install and how to use polib, read through the documentation listed below.
Contents:
Quick start guide¶
Installing polib¶
polib requires python 2.5 or superior.
There are several ways to install polib, this is explained in the installation section.
For the impatient, the easiest method is to install polib via pip, just type:
pip install polib
Some basics about gettext catalogs¶
A gettext catalog is made up of many entries, each entry holding the relation between an original untranslated string and its corresponding translation.
All entries in a given catalog usually pertain to a single project, and all translations are expressed in a single target language. One PO file entry has the following schematic structure:
# translator-comments
#. extracted-comments
#: reference...
#, flag...
msgid untranslated-string
msgstr translated-string
A simple entry can look like this:
#: lib/error.c:116
msgid "Unknown system error"
msgstr "Error desconegut del sistema"
polib has two main entry points for working with gettext catalogs:
- the pofile() and mofile() functions to load existing po or mo files,
- the POFile and MOFile classes to create new po or mo files.
References * Gettext Manual * PO file format * MO file format
Loading existing catalogs¶
Loading a catalog and detecting its encoding¶
Here the encoding of the po file is auto-detected by polib (polib detects it by parsing the charset in the header of the pofile):
import polib
po = polib.pofile('path/to/catalog.po')
Loading a catalog and specifying explicitly the encoding¶
For some reason you may want to specify the file encoding explicitely (because the charset is not specified in the po file header for example), to do so:
import polib
po = polib.pofile(
'path/to/catalog.po',
encoding='iso-8859-15'
)
Loading an mo file¶
In some cases you can be forced to load an mo file (because the po file is not available for example), polib handles this case:
import polib
mo = polib.mofile('path/to/catalog.mo')
print mo
As for po files, mofile also allows to specify the encoding explicitely.
Creating po catalogs from scratch¶
polib allows you to create catalog from scratch, this can be done with the POFile class, for exemple to create a simple catalog you could do:
import polib
po = polib.POFile()
po.metadata = {
'Project-Id-Version': '1.0',
'Report-Msgid-Bugs-To': 'you@example.com',
'POT-Creation-Date': '2007-10-18 14:00+0100',
'PO-Revision-Date': '2007-10-18 14:00+0100',
'Last-Translator': 'you <you@example.com>',
'Language-Team': 'English <yourteam@example.com>',
'MIME-Version': '1.0',
'Content-Type': 'text/plain; charset=utf-8',
'Content-Transfer-Encoding': '8bit',
}
This snippet creates an empty pofile, with its metadata, and now you can add you entries to the po file like this:
entry = polib.POEntry(
msgid=u'Welcome',
msgstr=u'Bienvenue',
occurrences=[('welcome.py', '12'), ('anotherfile.py', '34')]
)
po.append(entry)
To save your file to the disk you would just do:
po.save('/path/to/newfile.po')
And to compile the corresponding mo file:
po.save_as_mofile('/path/to/newfile.mo')
More examples¶
Iterating over entries¶
Iterating over all entries (by default POFiles contains all catalog entries, even obsolete and fuzzy entries):
import polib
po = polib.pofile('path/to/catalog.po')
for entry in po:
print entry.msgid, entry.msgstr
Iterating over all entries except obsolete entries:
import polib
po = polib.pofile('path/to/catalog.po')
valid_entries = [e for e in po if not e.obsolete]
for entry in valid_entries:
print entry.msgid, entry.msgstr
Iterating over translated entries only:
import polib
po = polib.pofile('path/to/catalog.po')
for entry in po.translated_entries():
print entry.msgid, entry.msgstr
And so on... You could also iterate over the list of POEntry objects returned by the following POFile methods:
Getting the percent of translated entries¶
import polib
po = polib.pofile('path/to/catalog.po')
print po.percent_translated()
Compiling po to mo files and reversing mo files to po files¶
Compiling a po file:
import polib
po = polib.pofile('path/to/catalog.po')
# to get the binary representation in a variable:
modata = po.to_binary()
# or to save the po file as an mo file
po.save_as_mofile('path/to/catalog.mo')
Reverse a mo file to a po file:
mo = polib.mofile('path/to/catalog.mo')
# to get the unicode representation in a variable, just do:
podata = unicode(mo)
# or to save the mo file as an po file
mo.save_as_pofile('path/to/catalog.po')
Installation guide¶
Requirements¶
polib requires python 2.5 or higher.
Installing polib¶
There are several ways to install polib:
- Automatically, via a package manager.
- Manually, by downloading a copy of the release package and installing it yourself.
- Manually, by performing a Mercurial checkout of the latest code.
Automatic installation via a package manager¶
Several automatic package-installation tools are available for Python; the most popular are pip and easy_install . Either can be used to install polib.
Using pip, type:
pip install polib
Using easy_install, type:
easy_install polib
It is also possible that your operating system distributor provides a packaged version of polib. Consult your operating system’s package list for details, but be aware that third-party distributions may be providing older versions of polib, and so you should consult the documentation which comes with your operating system’s package.
Manual installation from a downloaded package¶
If you prefer not to use an automated package installer, you can download a copy of polib and install it manually. The latest release package can be downloaded from polib’s page on the Python Package Index.
Once you’ve downloaded the package, unpack it, this will create the directory polib-X-Y-Z, which contains the setup.py installation script. From a command line in that directory, type:
python setup.py install
Note
On some systems you may need to execute this with administrative privileges (e.g., sudo python setup.py install).
Manual installation from a Mercurial checkout¶
If you’d like to try out the latest in-development code, you can obtain it from the polib repository, which is hosted at Bitbucket and uses Mercurial for version control.
To obtain the latest code and documentation, you’ll need to have Mercurial installed, at which point you can type:
hg clone http://bitbucket.org/izi/polib/
This will create a copy of the polib Mercurial repository on your computer; you can then add the polib.py file to your Python import path, or use the setup.py script to install as a package.
polib API¶
The pofile function¶
- polib.pofile(pofile, **kwargs)[source]¶
Convenience function that parses the po or pot file pofile and returns a POFile instance.
Arguments:
- pofile
- string, full or relative path to the po/pot file or its content (data).
- wrapwidth
- integer, the wrap width, only useful when the -w option was passed to xgettext (optional, default: 78).
- encoding
- string, the encoding to use (e.g. “utf-8”) (default: None, the encoding will be auto-detected).
- check_for_duplicates
- whether to check for duplicate entries when adding entries to the file (optional, default: False).
- klass
- class which is used to instantiate the return value (optional, default: None, the return value with be a POFile instance).
The mofile function¶
- polib.mofile(mofile, **kwargs)[source]¶
Convenience function that parses the mo file mofile and returns a MOFile instance.
Arguments:
- mofile
- string, full or relative path to the mo file or its content (data).
- wrapwidth
- integer, the wrap width, only useful when the -w option was passed to xgettext to generate the po file that was used to format the mo file (optional, default: 78).
- encoding
- string, the encoding to use (e.g. “utf-8”) (default: None, the encoding will be auto-detected).
- check_for_duplicates
- whether to check for duplicate entries when adding entries to the file (optional, default: False).
- klass
- class which is used to instantiate the return value (optional, default: None, the return value with be a POFile instance).
The detect_encoding function¶
- polib.detect_encoding(file, binary_mode=False)[source]¶
Try to detect the encoding used by the file. The file argument can be a PO or MO file path or a string containing the contents of the file. If the encoding cannot be detected, the function will return the value of default_encoding.
Arguments:
- file
- string, full or relative path to the po/mo file or its content.
- binary_mode
- boolean, set this to True if file is a mo file.
The escape function¶
The unescape function¶
The POFile class¶
- class polib.POFile(*args, **kwargs)[source]¶
Po (or Pot) file reader/writer. This class inherits the _BaseFile class and, by extension, the python list type.
- merge(refpot)[source]¶
Convenience method that merges the current pofile with the pot file provided. It behaves exactly as the gettext msgmerge utility:
- comments of this file will be preserved, but extracted comments and occurrences will be discarded;
- any translations or comments in the file will be discarded, however, dot comments and file positions will be preserved;
- the fuzzy flags are preserved.
Keyword argument:
- refpot
- object POFile, the reference catalog.
- percent_translated()[source]¶
Convenience method that returns the percentage of translated messages.
The MOFile class¶
- class polib.MOFile(*args, **kwargs)[source]¶
Mo file reader/writer. This class inherits the _BaseFile class and, by extension, the python list type.
- save(fpath=None)[source]¶
Saves the mofile to fpath.
Keyword argument:
- fpath
- string, full or relative path to the file.
The POEntry class¶
Contributing to polib¶
You are very welcome to contribute to the project! The bugtracker, wiki and mercurial repository can be found at the project’s page.
New releases are also published at the cheeseshop.
How to contribute¶
There are various possibilities to get involved, for example you can:
- Report bugs preferably with patches if you can;
- Enhance this documentation
- Fork the code, implement new features, test and send a pull request
Running the test suite¶
To run the tests, just type the following on a terminal:
$ cd /path/to/polib/
$ ./runtests.sh
If you want to generate coverage information:
$ pip install coverage
$ ./runtests.sh
$ coverage html
Projects using polib¶
polib is used by many opensource projects, here are some of them:
- Mercurial
- Transifex
- Launchpad ubuntu translator tools
- Django-rosetta
- The evergreen library system
- Qooxdoo
- http://www.linux.rk.edu.pl/tra/list/
- Lictionary
If you are using polib and wish to be listed here (or not) let me know.