# polib API

## The `pofile` function

polib.pofile(pofile, **kwargs)

  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)

  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 (string or bytes).

  `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)

  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

polib.escape(st)

  Escapes the characters `\\`, `\t`, `\n`, `\r`, `\v`, `\b`, `\f` and `"` in the given string `st` and returns it.

## The `unescape` function

polib.unescape(st)

  Unescapes the characters `\\`, `\t`, `\n`, `\r`, `\v`, `\b`, `\f` and `"` in the given string `st` and returns it.

## The `POFile` class

class polib.POFile(*args, **kwargs)

  Po (or Pot) file reader/writer. This class inherits the `_BaseFile` class and, by extension, the python `list` type.

  fuzzy_entries()

    Convenience method that returns the list of fuzzy entries.

  merge(refpot)

    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.

  obsolete_entries()

    Convenience method that returns the list of obsolete entries.

  percent_translated()

    Convenience method that returns the percentage of translated messages.

  save_as_mofile(fpath)

    Saves the binary representation of the file to given `fpath`.

    Keyword argument:

    `fpath`

      string, full or relative path to the mo file.

  translated_entries()

    Convenience method that returns the list of translated entries.

  untranslated_entries()

    Convenience method that returns the list of untranslated entries.

## The `MOFile` class

class polib.MOFile(*args, **kwargs)

  Mo file reader/writer. This class inherits the `_BaseFile` class and, by extension, the python `list` type.

  fuzzy_entries()

    Convenience method to keep the same interface with POFile instances.

  obsolete_entries()

    Convenience method to keep the same interface with POFile instances.

  percent_translated()

    Convenience method to keep the same interface with POFile instances.

  save(fpath=None)

    Saves the mofile to `fpath`.

    Keyword argument:

    `fpath`

      string, full or relative path to the file.

  save_as_pofile(fpath)

    Saves the mofile as a pofile to `fpath`.

    Keyword argument:

    `fpath`

      string, full or relative path to the file.

  translated_entries()

    Convenience method to keep the same interface with POFile instances.

  untranslated_entries()

    Convenience method to keep the same interface with POFile instances.

## The `POEntry` class

class polib.POEntry(*args, **kwargs)

  Represents a po file entry.

  merge(other)

    Merge the current entry with the given pot entry.

  translated()

    Returns `True` if the entry has been translated or `False` otherwise.

## The `MOEntry` class

class polib.MOEntry(*args, **kwargs)

  Represents a mo file entry.