# Quick start guide

## Installing polib

polib requires python 2.7 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 explicitly (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 a catalog from a string

If you have a catalog as a string variable, you can load it simply like this:

    import polib
    po_str = '''
    msgid ""
    msgstr ""
    "Project-Id-Version: django\n"

    msgid "foo"
    msgstr "bar"
    '''
    po = polib.pofile(po_str)

### 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 specifying the encoding explicitly.

## Loading an mo file from a bytes object

If you have a bytes representation of a n mo file in a variable, you can load it simply like this:

    import polib
    mo_bytes = b"\xde\x12\x04\x95\x00\x00\x00\x00\x05\x00\x00\x00\x1c\x00\x00\x00D\x00\x00\x00\x07\x00\x00\x00l\x00\x00\x00\x00\x00\x00\x00\x88\x00\x00\x00\x10\x00\x00\x00\x89\x00\x00\x00\x07\x00\x00\x00\x9a\x00\x00\x00\x0c\x00\x00\x00\xa2\x00\x00\x00\x0b\x00\x00\x00\xaf\x00\x00\x00(\x00\x00\x00\xbb\x00\x00\x00\n\x00\x00\x00\xe4\x00\x00\x00\x10\x00\x00\x00\xef\x00\x00\x00\x0f\x00\x00\x00\x00\x01\x00\x00\x16\x00\x00\x00\x10\x01\x00\x00\x01\x00\x00\x00\x03\x00\x00\x00\x05\x00\x00\x00\x00\x00\x00\x00\x04\x00\x00\x00\x00\x00\x00\x00\x02\x00\x00\x00\x00SNAR_BEZEICHNUNG\x00conform\x00inconclusive\x00non-conform\x00Content-Type: text/plain; charset=UTF-8\n\x00Feldfrucht\x00\xc3\x9cbereinstimmung\x00Nicht eindeutig\x00Keine \xc3\x9cbereinstimmung\x00"
    mo = polib.mofile(mo_bytes)

## Creating po catalogs from scratch

polib allows you to create catalog from scratch, this can be done with the POFile class, for example 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:

- `untranslated_entries()`

- `fuzzy_entries()`

### 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')