%% Generated by Sphinx.
\def\sphinxdocclass{report}
\documentclass[letterpaper,10pt,english]{sphinxmanual}
\ifdefined\pdfpxdimen
   \let\sphinxpxdimen\pdfpxdimen\else\newdimen\sphinxpxdimen
\fi \sphinxpxdimen=.75bp\relax
\ifdefined\pdfimageresolution
    \pdfimageresolution= \numexpr \dimexpr1in\relax/\sphinxpxdimen\relax
\fi
%% let collapsible pdf bookmarks panel have high depth per default
\PassOptionsToPackage{bookmarksdepth=5}{hyperref}

\PassOptionsToPackage{booktabs}{sphinx}
\PassOptionsToPackage{colorrows}{sphinx}

\PassOptionsToPackage{warn}{textcomp}
\usepackage[utf8]{inputenc}
\ifdefined\DeclareUnicodeCharacter
% support both utf8 and utf8x syntaxes
  \ifdefined\DeclareUnicodeCharacterAsOptional
    \def\sphinxDUC#1{\DeclareUnicodeCharacter{"#1}}
  \else
    \let\sphinxDUC\DeclareUnicodeCharacter
  \fi
  \sphinxDUC{00A0}{\nobreakspace}
  \sphinxDUC{2500}{\sphinxunichar{2500}}
  \sphinxDUC{2502}{\sphinxunichar{2502}}
  \sphinxDUC{2514}{\sphinxunichar{2514}}
  \sphinxDUC{251C}{\sphinxunichar{251C}}
  \sphinxDUC{2572}{\textbackslash}
\fi
\usepackage{cmap}
\usepackage[T1]{fontenc}
\usepackage{amsmath,amssymb,amstext}
\usepackage{babel}



\usepackage{tgtermes}
\usepackage{tgheros}
\renewcommand{\ttdefault}{txtt}



\usepackage[Bjarne]{fncychap}
\usepackage{sphinx}

\fvset{fontsize=auto}
\usepackage{geometry}


% Include hyperref last.
\usepackage{hyperref}
% Fix anchor placement for figures with captions.
\usepackage{hypcap}% it must be loaded after hyperref.
% Set up styles of URL: it should be placed after hyperref.
\urlstyle{same}


\usepackage{sphinxmessages}
\setcounter{tocdepth}{1}



\title{polib Documentation}
\date{Nov 24, 2024}
\release{1.2.0}
\author{David Jean Louis \textless{}izimobil@gmail.com\textgreater{}}
\newcommand{\sphinxlogo}{\vbox{}}
\renewcommand{\releasename}{Release}
\makeindex
\begin{document}

\ifdefined\shorthandoff
  \ifnum\catcode`\=\string=\active\shorthandoff{=}\fi
  \ifnum\catcode`\"=\active\shorthandoff{"}\fi
\fi

\pagestyle{empty}
\sphinxmaketitle
\pagestyle{plain}
\sphinxtableofcontents
\pagestyle{normal}
\phantomsection\label{\detokenize{index::doc}}


\sphinxAtStartPar
\sphinxhref{https://pypi.python.org/pypi/djangorestframework-datatables}{\sphinxincludegraphics{{/tmp/csb/polib-1.2.0/docs/_build/doctrees/images/14868b3241119cdcbc15559741242b47724ae704/polib}.svg}} \sphinxhref{https://pypistats.org/packages/polib}{\sphinxincludegraphics{{/tmp/csb/polib-1.2.0/docs/_build/doctrees/images/569023eaea8ae8cdd73b13c3443ec6c4dd285484/polib}.svg}} \sphinxhref{http://travis-ci.org/izimobil/polib?branch=master}{} \sphinxhref{https://codecov.io/gh/izimobil/polib}{\sphinxincludegraphics{{/tmp/csb/polib-1.2.0/docs/_build/doctrees/images/f854e68571ce44e2f3a52e4fab4777f1e2c57c7b/badge}.svg}} \sphinxhref{http://polib.readthedocs.io/en/latest/?badge=latest}{\sphinxincludegraphics{{/tmp/csb/polib-1.2.0/docs/_build/doctrees/images/76dabe0a03638af68c11dc1a9b34036aadcd78af/76dabe0a03638af68c11dc1a9b34036aadcd78af}.svg}} \sphinxhref{https://img.shields.io/pypi/pyversions/polib.svg}{\sphinxincludegraphics{{/tmp/csb/polib-1.2.0/docs/_build/doctrees/images/f33425bddaa2ea734ef7fa3cae03551a207290f3/polib}.svg}}

\sphinxAtStartPar
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.

\sphinxAtStartPar
polib supports out of the box any version of python ranging from 2.7 to latest
3.X version.

\sphinxAtStartPar
polib is pretty stable now and is used by many
{\hyperref[\detokenize{projects:projects}]{\sphinxcrossref{\DUrole{std}{\DUrole{std-ref}{opensource projects}}}}}.

\sphinxAtStartPar
polib is completely free and opensource, the license used is
\sphinxhref{http://www.opensource.org/licenses/mit-license.php}{the MIT license}.
It was developed back in 2006 by \sphinxhref{mailto:izimobil@gmail.com}{David Jean Louis}
and it is still actively maintained.

\sphinxAtStartPar
To get up and running quickly, consult the {\hyperref[\detokenize{quickstart:quickstart}]{\sphinxcrossref{\DUrole{std}{\DUrole{std-ref}{quick\sphinxhyphen{}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.

\sphinxAtStartPar
Contents:

\sphinxstepscope


\chapter{Quick start guide}
\label{\detokenize{quickstart:quick-start-guide}}\label{\detokenize{quickstart:quickstart}}\label{\detokenize{quickstart::doc}}

\section{Installing polib}
\label{\detokenize{quickstart:installing-polib}}
\sphinxAtStartPar
polib requires python 2.7 or superior.

\sphinxAtStartPar
There are several ways to install polib, this is explained
in {\hyperref[\detokenize{installation:installation}]{\sphinxcrossref{\DUrole{std}{\DUrole{std-ref}{the installation section}}}}}.

\sphinxAtStartPar
For the impatient, the easiest method is to install polib via
\sphinxhref{http://pip.openplans.org/}{pip}, just type:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{n}{pip} \PYG{n}{install} \PYG{n}{polib}
\end{sphinxVerbatim}


\section{Some basics about gettext catalogs}
\label{\detokenize{quickstart:some-basics-about-gettext-catalogs}}
\sphinxAtStartPar
A gettext catalog is made up of many entries, each entry holding the relation
between an original untranslated string and its corresponding translation.

\sphinxAtStartPar
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:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{c+c1}{\PYGZsh{}  translator\PYGZhy{}comments}
\PYG{c+c1}{\PYGZsh{}. extracted\PYGZhy{}comments}
\PYG{c+c1}{\PYGZsh{}: reference...}
\PYG{c+c1}{\PYGZsh{}, flag...}
\PYG{n}{msgid} \PYG{n}{untranslated}\PYG{o}{\PYGZhy{}}\PYG{n}{string}
\PYG{n}{msgstr} \PYG{n}{translated}\PYG{o}{\PYGZhy{}}\PYG{n}{string}
\end{sphinxVerbatim}

\sphinxAtStartPar
A simple entry can look like this:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{c+c1}{\PYGZsh{}: lib/error.c:116}
\PYG{n}{msgid} \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{Unknown system error}\PYG{l+s+s2}{\PYGZdq{}}
\PYG{n}{msgstr} \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{Error desconegut del sistema}\PYG{l+s+s2}{\PYGZdq{}}
\end{sphinxVerbatim}

\sphinxAtStartPar
polib has two main entry points for working with gettext catalogs:
\begin{itemize}
\item {} 
\sphinxAtStartPar
the {\hyperref[\detokenize{api:polib.pofile}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{pofile()}}}}} and {\hyperref[\detokenize{api:polib.mofile}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{mofile()}}}}} functions to \sphinxstylestrong{load}
existing po or mo files,

\item {} 
\sphinxAtStartPar
the {\hyperref[\detokenize{api:polib.POFile}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{POFile}}}}} and {\hyperref[\detokenize{api:polib.MOFile}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{MOFile}}}}} classes to \sphinxstylestrong{create}
new po or mo files.

\end{itemize}

\sphinxAtStartPar
References
\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxhref{http://www.gnu.org/software/gettext/manual/}{Gettext Manual}

\item {} 
\sphinxAtStartPar
\sphinxhref{http://www.gnu.org/software/gettext/manual/html\_node/gettext\_9.html}{PO file format}

\item {} 
\sphinxAtStartPar
\sphinxhref{http://www.gnu.org/software/gettext/manual/html\_node/gettext\_136.html}{MO file format}

\end{itemize}


\section{Loading existing catalogs}
\label{\detokenize{quickstart:loading-existing-catalogs}}

\subsection{Loading a catalog and detecting its encoding}
\label{\detokenize{quickstart:loading-a-catalog-and-detecting-its-encoding}}
\sphinxAtStartPar
Here the encoding of the po file is auto\sphinxhyphen{}detected by polib (polib detects it by
parsing the charset in the header of the pofile):

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{k+kn}{import} \PYG{n+nn}{polib}
\PYG{n}{po} \PYG{o}{=} \PYG{n}{polib}\PYG{o}{.}\PYG{n}{pofile}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{path/to/catalog.po}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{)}
\end{sphinxVerbatim}


\subsection{Loading a catalog and specifying explicitly the encoding}
\label{\detokenize{quickstart:loading-a-catalog-and-specifying-explicitly-the-encoding}}
\sphinxAtStartPar
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:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{k+kn}{import} \PYG{n+nn}{polib}
\PYG{n}{po} \PYG{o}{=} \PYG{n}{polib}\PYG{o}{.}\PYG{n}{pofile}\PYG{p}{(}
    \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{path/to/catalog.po}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}
    \PYG{n}{encoding}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{iso\PYGZhy{}8859\PYGZhy{}15}\PYG{l+s+s1}{\PYGZsq{}}
\PYG{p}{)}
\end{sphinxVerbatim}


\section{Loading a catalog from a string}
\label{\detokenize{quickstart:loading-a-catalog-from-a-string}}
\sphinxAtStartPar
If you have a catalog as a string variable, you can load it simply like this:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{k+kn}{import} \PYG{n+nn}{polib}
\PYG{n}{po\PYGZus{}str} \PYG{o}{=} \PYG{l+s+s1}{\PYGZsq{}\PYGZsq{}\PYGZsq{}}
\PYG{l+s+s1}{msgid }\PYG{l+s+s1}{\PYGZdq{}}\PYG{l+s+s1}{\PYGZdq{}}
\PYG{l+s+s1}{msgstr }\PYG{l+s+s1}{\PYGZdq{}}\PYG{l+s+s1}{\PYGZdq{}}
\PYG{l+s+s1}{\PYGZdq{}}\PYG{l+s+s1}{Project\PYGZhy{}Id\PYGZhy{}Version: django}\PYG{l+s+se}{\PYGZbs{}n}\PYG{l+s+s1}{\PYGZdq{}}

\PYG{l+s+s1}{msgid }\PYG{l+s+s1}{\PYGZdq{}}\PYG{l+s+s1}{foo}\PYG{l+s+s1}{\PYGZdq{}}
\PYG{l+s+s1}{msgstr }\PYG{l+s+s1}{\PYGZdq{}}\PYG{l+s+s1}{bar}\PYG{l+s+s1}{\PYGZdq{}}
\PYG{l+s+s1}{\PYGZsq{}\PYGZsq{}\PYGZsq{}}
\PYG{n}{po} \PYG{o}{=} \PYG{n}{polib}\PYG{o}{.}\PYG{n}{pofile}\PYG{p}{(}\PYG{n}{po\PYGZus{}str}\PYG{p}{)}
\end{sphinxVerbatim}


\subsection{Loading an mo file}
\label{\detokenize{quickstart:loading-an-mo-file}}
\sphinxAtStartPar
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:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{k+kn}{import} \PYG{n+nn}{polib}
\PYG{n}{mo} \PYG{o}{=} \PYG{n}{polib}\PYG{o}{.}\PYG{n}{mofile}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{path/to/catalog.mo}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{)}
\PYG{n+nb}{print}\PYG{p}{(}\PYG{n}{mo}\PYG{p}{)}
\end{sphinxVerbatim}

\sphinxAtStartPar
As for po files, mofile also allows specifying the encoding explicitly.


\section{Loading an mo file from a bytes object}
\label{\detokenize{quickstart:loading-an-mo-file-from-a-bytes-object}}
\sphinxAtStartPar
If you have a bytes representation of a n mo file in a variable,
you can load it simply like this:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{k+kn}{import} \PYG{n+nn}{polib}
\PYG{n}{mo\PYGZus{}bytes} \PYG{o}{=} \PYG{l+s+sa}{b}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+se}{\PYGZbs{}xde}\PYG{l+s+se}{\PYGZbs{}x12}\PYG{l+s+se}{\PYGZbs{}x04}\PYG{l+s+se}{\PYGZbs{}x95}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x05}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x1c}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+s2}{D}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x07}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+s2}{l}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x88}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x10}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x89}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x07}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x9a}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x0c}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}xa2}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x0b}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}xaf}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+s2}{(}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}xbb}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}n}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}xe4}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x10}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}xef}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x0f}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x01}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x16}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x10}\PYG{l+s+se}{\PYGZbs{}x01}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x01}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x03}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x05}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x04}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x02}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+s2}{SNAR\PYGZus{}BEZEICHNUNG}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+s2}{conform}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+s2}{inconclusive}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+s2}{non\PYGZhy{}conform}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+s2}{Content\PYGZhy{}Type: text/plain; charset=UTF\PYGZhy{}8}\PYG{l+s+se}{\PYGZbs{}n}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+s2}{Feldfrucht}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+se}{\PYGZbs{}xc3}\PYG{l+s+se}{\PYGZbs{}x9c}\PYG{l+s+s2}{bereinstimmung}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+s2}{Nicht eindeutig}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+s2}{Keine }\PYG{l+s+se}{\PYGZbs{}xc3}\PYG{l+s+se}{\PYGZbs{}x9c}\PYG{l+s+s2}{bereinstimmung}\PYG{l+s+se}{\PYGZbs{}x00}\PYG{l+s+s2}{\PYGZdq{}}
\PYG{n}{mo} \PYG{o}{=} \PYG{n}{polib}\PYG{o}{.}\PYG{n}{mofile}\PYG{p}{(}\PYG{n}{mo\PYGZus{}bytes}\PYG{p}{)}
\end{sphinxVerbatim}


\section{Creating po catalogs from scratch}
\label{\detokenize{quickstart:creating-po-catalogs-from-scratch}}
\sphinxAtStartPar
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:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{k+kn}{import} \PYG{n+nn}{polib}

\PYG{n}{po} \PYG{o}{=} \PYG{n}{polib}\PYG{o}{.}\PYG{n}{POFile}\PYG{p}{(}\PYG{p}{)}
\PYG{n}{po}\PYG{o}{.}\PYG{n}{metadata} \PYG{o}{=} \PYG{p}{\PYGZob{}}
    \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Project\PYGZhy{}Id\PYGZhy{}Version}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{1.0}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}
    \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Report\PYGZhy{}Msgid\PYGZhy{}Bugs\PYGZhy{}To}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{you@example.com}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}
    \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{POT\PYGZhy{}Creation\PYGZhy{}Date}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{2007\PYGZhy{}10\PYGZhy{}18 14:00+0100}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}
    \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{PO\PYGZhy{}Revision\PYGZhy{}Date}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{2007\PYGZhy{}10\PYGZhy{}18 14:00+0100}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}
    \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Last\PYGZhy{}Translator}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{you \PYGZlt{}you@example.com\PYGZgt{}}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}
    \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Language\PYGZhy{}Team}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{English \PYGZlt{}yourteam@example.com\PYGZgt{}}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}
    \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{MIME\PYGZhy{}Version}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{1.0}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}
    \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Content\PYGZhy{}Type}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{text/plain; charset=utf\PYGZhy{}8}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}
    \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Content\PYGZhy{}Transfer\PYGZhy{}Encoding}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{8bit}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}
\PYG{p}{\PYGZcb{}}
\end{sphinxVerbatim}

\sphinxAtStartPar
This snippet creates an empty pofile, with its metadata, and now you can add
you entries to the po file like this:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{n}{entry} \PYG{o}{=} \PYG{n}{polib}\PYG{o}{.}\PYG{n}{POEntry}\PYG{p}{(}
    \PYG{n}{msgid}\PYG{o}{=}\PYG{l+s+sa}{u}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Welcome}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}
    \PYG{n}{msgstr}\PYG{o}{=}\PYG{l+s+sa}{u}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Bienvenue}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}
    \PYG{n}{occurrences}\PYG{o}{=}\PYG{p}{[}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{welcome.py}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{12}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{)}\PYG{p}{,} \PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{anotherfile.py}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{34}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{)}\PYG{p}{]}
\PYG{p}{)}
\PYG{n}{po}\PYG{o}{.}\PYG{n}{append}\PYG{p}{(}\PYG{n}{entry}\PYG{p}{)}
\end{sphinxVerbatim}

\sphinxAtStartPar
To save your file to the disk you would just do:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{n}{po}\PYG{o}{.}\PYG{n}{save}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{/path/to/newfile.po}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{)}
\end{sphinxVerbatim}

\sphinxAtStartPar
And to compile the corresponding mo file:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{n}{po}\PYG{o}{.}\PYG{n}{save\PYGZus{}as\PYGZus{}mofile}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{/path/to/newfile.mo}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{)}
\end{sphinxVerbatim}


\section{More examples}
\label{\detokenize{quickstart:more-examples}}

\subsection{Iterating over entries}
\label{\detokenize{quickstart:iterating-over-entries}}
\sphinxAtStartPar
Iterating over \sphinxstylestrong{all} entries (by default POFiles contains all catalog
entries, even obsolete and fuzzy entries):

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{k+kn}{import} \PYG{n+nn}{polib}

\PYG{n}{po} \PYG{o}{=} \PYG{n}{polib}\PYG{o}{.}\PYG{n}{pofile}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{path/to/catalog.po}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{)}
\PYG{k}{for} \PYG{n}{entry} \PYG{o+ow}{in} \PYG{n}{po}\PYG{p}{:}
    \PYG{n+nb}{print}\PYG{p}{(}\PYG{n}{entry}\PYG{o}{.}\PYG{n}{msgid}\PYG{p}{,} \PYG{n}{entry}\PYG{o}{.}\PYG{n}{msgstr}\PYG{p}{)}
\end{sphinxVerbatim}

\sphinxAtStartPar
Iterating over \sphinxstylestrong{all} entries except obsolete entries:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{k+kn}{import} \PYG{n+nn}{polib}

\PYG{n}{po} \PYG{o}{=} \PYG{n}{polib}\PYG{o}{.}\PYG{n}{pofile}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{path/to/catalog.po}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{)}
\PYG{n}{valid\PYGZus{}entries} \PYG{o}{=} \PYG{p}{[}\PYG{n}{e} \PYG{k}{for} \PYG{n}{e} \PYG{o+ow}{in} \PYG{n}{po} \PYG{k}{if} \PYG{o+ow}{not} \PYG{n}{e}\PYG{o}{.}\PYG{n}{obsolete}\PYG{p}{]}
\PYG{k}{for} \PYG{n}{entry} \PYG{o+ow}{in} \PYG{n}{valid\PYGZus{}entries}\PYG{p}{:}
    \PYG{n+nb}{print}\PYG{p}{(}\PYG{n}{entry}\PYG{o}{.}\PYG{n}{msgid}\PYG{p}{,} \PYG{n}{entry}\PYG{o}{.}\PYG{n}{msgstr}\PYG{p}{)}
\end{sphinxVerbatim}

\sphinxAtStartPar
Iterating over translated entries only:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{k+kn}{import} \PYG{n+nn}{polib}

\PYG{n}{po} \PYG{o}{=} \PYG{n}{polib}\PYG{o}{.}\PYG{n}{pofile}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{path/to/catalog.po}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{)}
\PYG{k}{for} \PYG{n}{entry} \PYG{o+ow}{in} \PYG{n}{po}\PYG{o}{.}\PYG{n}{translated\PYGZus{}entries}\PYG{p}{(}\PYG{p}{)}\PYG{p}{:}
    \PYG{n+nb}{print}\PYG{p}{(}\PYG{n}{entry}\PYG{o}{.}\PYG{n}{msgid}\PYG{p}{,} \PYG{n}{entry}\PYG{o}{.}\PYG{n}{msgstr}\PYG{p}{)}
\end{sphinxVerbatim}

\sphinxAtStartPar
And so on…
You could also iterate over the list of POEntry objects returned by the
following POFile methods:
\begin{itemize}
\item {} 
\sphinxAtStartPar
{\hyperref[\detokenize{api:polib.POFile.untranslated_entries}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{untranslated\_entries()}}}}}

\item {} 
\sphinxAtStartPar
{\hyperref[\detokenize{api:polib.POFile.fuzzy_entries}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{fuzzy\_entries()}}}}}

\end{itemize}


\subsection{Getting the percent of translated entries}
\label{\detokenize{quickstart:getting-the-percent-of-translated-entries}}
\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{k+kn}{import} \PYG{n+nn}{polib}

\PYG{n}{po} \PYG{o}{=} \PYG{n}{polib}\PYG{o}{.}\PYG{n}{pofile}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{path/to/catalog.po}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{)}
\PYG{n+nb}{print}\PYG{p}{(}\PYG{n}{po}\PYG{o}{.}\PYG{n}{percent\PYGZus{}translated}\PYG{p}{(}\PYG{p}{)}\PYG{p}{)}
\end{sphinxVerbatim}


\subsection{Compiling po to mo files and reversing mo files to po files}
\label{\detokenize{quickstart:compiling-po-to-mo-files-and-reversing-mo-files-to-po-files}}
\sphinxAtStartPar
Compiling a po file:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{k+kn}{import} \PYG{n+nn}{polib}

\PYG{n}{po} \PYG{o}{=} \PYG{n}{polib}\PYG{o}{.}\PYG{n}{pofile}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{path/to/catalog.po}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{)}
\PYG{c+c1}{\PYGZsh{} to get the binary representation in a variable:}
\PYG{n}{modata} \PYG{o}{=} \PYG{n}{po}\PYG{o}{.}\PYG{n}{to\PYGZus{}binary}\PYG{p}{(}\PYG{p}{)}
\PYG{c+c1}{\PYGZsh{} or to save the po file as an mo file}
\PYG{n}{po}\PYG{o}{.}\PYG{n}{save\PYGZus{}as\PYGZus{}mofile}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{path/to/catalog.mo}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{)}
\end{sphinxVerbatim}

\sphinxAtStartPar
Reverse a mo file to a po file:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{n}{mo} \PYG{o}{=} \PYG{n}{polib}\PYG{o}{.}\PYG{n}{mofile}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{path/to/catalog.mo}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{)}
\PYG{c+c1}{\PYGZsh{} to get the unicode representation in a variable, just do:}
\PYG{n}{podata} \PYG{o}{=} \PYG{n}{unicode}\PYG{p}{(}\PYG{n}{mo}\PYG{p}{)}
\PYG{c+c1}{\PYGZsh{} or to save the mo file as an po file}
\PYG{n}{mo}\PYG{o}{.}\PYG{n}{save\PYGZus{}as\PYGZus{}pofile}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{path/to/catalog.po}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{)}
\end{sphinxVerbatim}

\sphinxstepscope


\chapter{Installation guide}
\label{\detokenize{installation:installation-guide}}\label{\detokenize{installation:installation}}\label{\detokenize{installation::doc}}

\section{Requirements}
\label{\detokenize{installation:requirements}}
\sphinxAtStartPar
polib requires python 2.7 or higher.


\section{Installing polib}
\label{\detokenize{installation:installing-polib}}
\sphinxAtStartPar
There are several ways to install polib:
\begin{itemize}
\item {} 
\sphinxAtStartPar
Automatically, via a package manager.

\item {} 
\sphinxAtStartPar
Manually, by downloading a copy of the release package and
installing it yourself.

\item {} 
\sphinxAtStartPar
Manually, by performing a Mercurial checkout of the latest code.

\end{itemize}


\subsection{Automatic installation via a package manager}
\label{\detokenize{installation:automatic-installation-via-a-package-manager}}
\sphinxAtStartPar
Several automatic package\sphinxhyphen{}installation tools are available for Python;
the most popular are \sphinxhref{http://pip.openplans.org/}{pip} and \sphinxhref{http://peak.telecommunity.com/DevCenter/EasyInstall}{easy\_install}  .
Either can be used to install polib.

\sphinxAtStartPar
Using \sphinxcode{\sphinxupquote{pip}}, type:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{n}{pip} \PYG{n}{install} \PYG{n}{polib}
\end{sphinxVerbatim}

\sphinxAtStartPar
Using \sphinxcode{\sphinxupquote{easy\_install}}, type:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{n}{easy\PYGZus{}install} \PYG{n}{polib}
\end{sphinxVerbatim}

\sphinxAtStartPar
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\sphinxhyphen{}party distributions may be providing older
versions of polib, and so you should consult the documentation which comes
with your operating system’s package.


\subsection{Manual installation from a downloaded package}
\label{\detokenize{installation:manual-installation-from-a-downloaded-package}}
\sphinxAtStartPar
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 \sphinxhref{http://pypi.python.org/pypi/polib/}{polib’s page on the Python Package Index}.

\sphinxAtStartPar
Once you’ve downloaded the package, unpack it, this will create the directory
\sphinxcode{\sphinxupquote{polib\sphinxhyphen{}X\sphinxhyphen{}Y\sphinxhyphen{}Z}}, which contains the \sphinxcode{\sphinxupquote{setup.py}} installation script.
From a command line in that directory, type:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{n}{python} \PYG{n}{setup}\PYG{o}{.}\PYG{n}{py} \PYG{n}{install}
\end{sphinxVerbatim}

\begin{sphinxadmonition}{note}{Note:}
\sphinxAtStartPar
On some systems you may need to execute this with administrative
privileges (e.g., \sphinxcode{\sphinxupquote{sudo python setup.py install}}).
\end{sphinxadmonition}


\subsection{Manual installation from a Git checkout}
\label{\detokenize{installation:manual-installation-from-a-git-checkout}}
\sphinxAtStartPar
If you’d like to try out the latest in\sphinxhyphen{}development code, you can obtain it
from the polib repository, which is hosted at
\sphinxhref{https://github.com/}{Github} and uses \sphinxhref{https://git-scm.com/}{Git} for version control.

\sphinxAtStartPar
To obtain the latest code and documentation, you’ll need to have Git
installed, at which point you can type:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{n}{git} \PYG{n}{clone} \PYG{n}{https}\PYG{p}{:}\PYG{o}{/}\PYG{o}{/}\PYG{n}{github}\PYG{o}{.}\PYG{n}{com}\PYG{o}{/}\PYG{n}{izimobil}\PYG{o}{/}\PYG{n}{polib}\PYG{o}{/}
\end{sphinxVerbatim}

\sphinxAtStartPar
This will create a copy of the polib Git repository on your computer;
you can then add the \sphinxcode{\sphinxupquote{polib.py}} file to your Python import path, or use the
\sphinxcode{\sphinxupquote{setup.py}} script to install as a package.

\sphinxstepscope


\chapter{polib API}
\label{\detokenize{api:polib-api}}\label{\detokenize{api:api}}\label{\detokenize{api::doc}}

\section{The \sphinxstyleliteralintitle{\sphinxupquote{pofile}} function}
\label{\detokenize{api:the-pofile-function}}\index{pofile() (in module polib)@\spxentry{pofile()}\spxextra{in module polib}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{api:polib.pofile}}
\pysigstartsignatures
\pysiglinewithargsret
{\sphinxcode{\sphinxupquote{polib.}}\sphinxbfcode{\sphinxupquote{pofile}}}
{\sphinxparam{\DUrole{n}{pofile}}\sphinxparamcomma \sphinxparam{\DUrole{o}{**}\DUrole{n}{kwargs}}}
{}
\pysigstopsignatures
\sphinxAtStartPar
Convenience function that parses the po or pot file \sphinxcode{\sphinxupquote{pofile}} and returns
a {\hyperref[\detokenize{api:polib.POFile}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{POFile}}}}} instance.

\sphinxAtStartPar
Arguments:
\begin{description}
\sphinxlineitem{\sphinxcode{\sphinxupquote{pofile}}}
\sphinxAtStartPar
string, full or relative path to the po/pot file or its content (data).

\sphinxlineitem{\sphinxcode{\sphinxupquote{wrapwidth}}}
\sphinxAtStartPar
integer, the wrap width, only useful when the \sphinxcode{\sphinxupquote{\sphinxhyphen{}w}} option was passed
to xgettext (optional, default: \sphinxcode{\sphinxupquote{78}}).

\sphinxlineitem{\sphinxcode{\sphinxupquote{encoding}}}
\sphinxAtStartPar
string, the encoding to use (e.g. “utf\sphinxhyphen{}8”) (default: \sphinxcode{\sphinxupquote{None}}, the
encoding will be auto\sphinxhyphen{}detected).

\sphinxlineitem{\sphinxcode{\sphinxupquote{check\_for\_duplicates}}}
\sphinxAtStartPar
whether to check for duplicate entries when adding entries to the
file (optional, default: \sphinxcode{\sphinxupquote{False}}).

\sphinxlineitem{\sphinxcode{\sphinxupquote{klass}}}
\sphinxAtStartPar
class which is used to instantiate the return value (optional,
default: \sphinxcode{\sphinxupquote{None}}, the return value with be a {\hyperref[\detokenize{api:polib.POFile}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{POFile}}}}}
instance).

\end{description}

\end{fulllineitems}



\section{The \sphinxstyleliteralintitle{\sphinxupquote{mofile}} function}
\label{\detokenize{api:the-mofile-function}}\index{mofile() (in module polib)@\spxentry{mofile()}\spxextra{in module polib}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{api:polib.mofile}}
\pysigstartsignatures
\pysiglinewithargsret
{\sphinxcode{\sphinxupquote{polib.}}\sphinxbfcode{\sphinxupquote{mofile}}}
{\sphinxparam{\DUrole{n}{mofile}}\sphinxparamcomma \sphinxparam{\DUrole{o}{**}\DUrole{n}{kwargs}}}
{}
\pysigstopsignatures
\sphinxAtStartPar
Convenience function that parses the mo file \sphinxcode{\sphinxupquote{mofile}} and returns a
{\hyperref[\detokenize{api:polib.MOFile}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{MOFile}}}}} instance.

\sphinxAtStartPar
Arguments:
\begin{description}
\sphinxlineitem{\sphinxcode{\sphinxupquote{mofile}}}
\sphinxAtStartPar
string, full or relative path to the mo file or its content (string
or bytes).

\sphinxlineitem{\sphinxcode{\sphinxupquote{wrapwidth}}}
\sphinxAtStartPar
integer, the wrap width, only useful when the \sphinxcode{\sphinxupquote{\sphinxhyphen{}w}} option was passed
to xgettext to generate the po file that was used to format the mo file
(optional, default: \sphinxcode{\sphinxupquote{78}}).

\sphinxlineitem{\sphinxcode{\sphinxupquote{encoding}}}
\sphinxAtStartPar
string, the encoding to use (e.g. “utf\sphinxhyphen{}8”) (default: \sphinxcode{\sphinxupquote{None}}, the
encoding will be auto\sphinxhyphen{}detected).

\sphinxlineitem{\sphinxcode{\sphinxupquote{check\_for\_duplicates}}}
\sphinxAtStartPar
whether to check for duplicate entries when adding entries to the
file (optional, default: \sphinxcode{\sphinxupquote{False}}).

\sphinxlineitem{\sphinxcode{\sphinxupquote{klass}}}
\sphinxAtStartPar
class which is used to instantiate the return value (optional,
default: \sphinxcode{\sphinxupquote{None}}, the return value with be a {\hyperref[\detokenize{api:polib.POFile}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{POFile}}}}}
instance).

\end{description}

\end{fulllineitems}



\section{The \sphinxstyleliteralintitle{\sphinxupquote{detect\_encoding}} function}
\label{\detokenize{api:the-detect-encoding-function}}\index{detect\_encoding() (in module polib)@\spxentry{detect\_encoding()}\spxextra{in module polib}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{api:polib.detect_encoding}}
\pysigstartsignatures
\pysiglinewithargsret
{\sphinxcode{\sphinxupquote{polib.}}\sphinxbfcode{\sphinxupquote{detect\_encoding}}}
{\sphinxparam{\DUrole{n}{file}}\sphinxparamcomma \sphinxparam{\DUrole{n}{binary\_mode}\DUrole{o}{=}\DUrole{default_value}{False}}}
{}
\pysigstopsignatures
\sphinxAtStartPar
Try to detect the encoding used by the \sphinxcode{\sphinxupquote{file}}. The \sphinxcode{\sphinxupquote{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
\sphinxcode{\sphinxupquote{default\_encoding}}.

\sphinxAtStartPar
Arguments:
\begin{description}
\sphinxlineitem{\sphinxcode{\sphinxupquote{file}}}
\sphinxAtStartPar
string, full or relative path to the po/mo file or its content.

\sphinxlineitem{\sphinxcode{\sphinxupquote{binary\_mode}}}
\sphinxAtStartPar
boolean, set this to True if \sphinxcode{\sphinxupquote{file}} is a mo file.

\end{description}

\end{fulllineitems}



\section{The \sphinxstyleliteralintitle{\sphinxupquote{escape}} function}
\label{\detokenize{api:the-escape-function}}\index{escape() (in module polib)@\spxentry{escape()}\spxextra{in module polib}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{api:polib.escape}}
\pysigstartsignatures
\pysiglinewithargsret
{\sphinxcode{\sphinxupquote{polib.}}\sphinxbfcode{\sphinxupquote{escape}}}
{\sphinxparam{\DUrole{n}{st}}}
{}
\pysigstopsignatures
\sphinxAtStartPar
Escapes the characters \sphinxcode{\sphinxupquote{\textbackslash{}\textbackslash{}}}, \sphinxcode{\sphinxupquote{\textbackslash{}t}}, \sphinxcode{\sphinxupquote{\textbackslash{}n}}, \sphinxcode{\sphinxupquote{\textbackslash{}r}}, \sphinxcode{\sphinxupquote{\textbackslash{}v}},
\sphinxcode{\sphinxupquote{\textbackslash{}b}}, \sphinxcode{\sphinxupquote{\textbackslash{}f}} and \sphinxcode{\sphinxupquote{"}} in the given string \sphinxcode{\sphinxupquote{st}} and returns it.

\end{fulllineitems}



\section{The \sphinxstyleliteralintitle{\sphinxupquote{unescape}} function}
\label{\detokenize{api:the-unescape-function}}\index{unescape() (in module polib)@\spxentry{unescape()}\spxextra{in module polib}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{api:polib.unescape}}
\pysigstartsignatures
\pysiglinewithargsret
{\sphinxcode{\sphinxupquote{polib.}}\sphinxbfcode{\sphinxupquote{unescape}}}
{\sphinxparam{\DUrole{n}{st}}}
{}
\pysigstopsignatures
\sphinxAtStartPar
Unescapes the characters \sphinxcode{\sphinxupquote{\textbackslash{}\textbackslash{}}}, \sphinxcode{\sphinxupquote{\textbackslash{}t}}, \sphinxcode{\sphinxupquote{\textbackslash{}n}}, \sphinxcode{\sphinxupquote{\textbackslash{}r}}, \sphinxcode{\sphinxupquote{\textbackslash{}v}},
\sphinxcode{\sphinxupquote{\textbackslash{}b}}, \sphinxcode{\sphinxupquote{\textbackslash{}f}} and \sphinxcode{\sphinxupquote{"}} in the given string \sphinxcode{\sphinxupquote{st}} and returns it.

\end{fulllineitems}



\section{The \sphinxstyleliteralintitle{\sphinxupquote{POFile}} class}
\label{\detokenize{api:the-pofile-class}}\index{POFile (class in polib)@\spxentry{POFile}\spxextra{class in polib}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{api:polib.POFile}}
\pysigstartsignatures
\pysiglinewithargsret
{\sphinxbfcode{\sphinxupquote{class\DUrole{w}{ }}}\sphinxcode{\sphinxupquote{polib.}}\sphinxbfcode{\sphinxupquote{POFile}}}
{\sphinxparam{\DUrole{o}{*}\DUrole{n}{args}}\sphinxparamcomma \sphinxparam{\DUrole{o}{**}\DUrole{n}{kwargs}}}
{}
\pysigstopsignatures
\sphinxAtStartPar
Po (or Pot) file reader/writer.
This class inherits the \sphinxcode{\sphinxupquote{\_BaseFile}} class and, by extension,
the python \sphinxcode{\sphinxupquote{list}} type.
\index{fuzzy\_entries() (polib.POFile method)@\spxentry{fuzzy\_entries()}\spxextra{polib.POFile method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{api:polib.POFile.fuzzy_entries}}
\pysigstartsignatures
\pysiglinewithargsret
{\sphinxbfcode{\sphinxupquote{fuzzy\_entries}}}
{}
{}
\pysigstopsignatures
\sphinxAtStartPar
Convenience method that returns the list of fuzzy entries.

\end{fulllineitems}

\index{merge() (polib.POFile method)@\spxentry{merge()}\spxextra{polib.POFile method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{api:polib.POFile.merge}}
\pysigstartsignatures
\pysiglinewithargsret
{\sphinxbfcode{\sphinxupquote{merge}}}
{\sphinxparam{\DUrole{n}{refpot}}}
{}
\pysigstopsignatures
\sphinxAtStartPar
Convenience method that merges the current pofile with the pot file
provided. It behaves exactly as the gettext msgmerge utility:
\begin{itemize}
\item {} 
\sphinxAtStartPar
comments of this file will be preserved, but extracted comments and
occurrences will be discarded;

\item {} 
\sphinxAtStartPar
any translations or comments in the file will be discarded, however,
dot comments and file positions will be preserved;

\item {} 
\sphinxAtStartPar
the fuzzy flags are preserved.

\end{itemize}

\sphinxAtStartPar
Keyword argument:
\begin{description}
\sphinxlineitem{\sphinxcode{\sphinxupquote{refpot}}}
\sphinxAtStartPar
object POFile, the reference catalog.

\end{description}

\end{fulllineitems}

\index{obsolete\_entries() (polib.POFile method)@\spxentry{obsolete\_entries()}\spxextra{polib.POFile method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{api:polib.POFile.obsolete_entries}}
\pysigstartsignatures
\pysiglinewithargsret
{\sphinxbfcode{\sphinxupquote{obsolete\_entries}}}
{}
{}
\pysigstopsignatures
\sphinxAtStartPar
Convenience method that returns the list of obsolete entries.

\end{fulllineitems}

\index{percent\_translated() (polib.POFile method)@\spxentry{percent\_translated()}\spxextra{polib.POFile method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{api:polib.POFile.percent_translated}}
\pysigstartsignatures
\pysiglinewithargsret
{\sphinxbfcode{\sphinxupquote{percent\_translated}}}
{}
{}
\pysigstopsignatures
\sphinxAtStartPar
Convenience method that returns the percentage of translated
messages.

\end{fulllineitems}

\index{save\_as\_mofile() (polib.POFile method)@\spxentry{save\_as\_mofile()}\spxextra{polib.POFile method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{api:polib.POFile.save_as_mofile}}
\pysigstartsignatures
\pysiglinewithargsret
{\sphinxbfcode{\sphinxupquote{save\_as\_mofile}}}
{\sphinxparam{\DUrole{n}{fpath}}}
{}
\pysigstopsignatures
\sphinxAtStartPar
Saves the binary representation of the file to given \sphinxcode{\sphinxupquote{fpath}}.

\sphinxAtStartPar
Keyword argument:
\begin{description}
\sphinxlineitem{\sphinxcode{\sphinxupquote{fpath}}}
\sphinxAtStartPar
string, full or relative path to the mo file.

\end{description}

\end{fulllineitems}

\index{translated\_entries() (polib.POFile method)@\spxentry{translated\_entries()}\spxextra{polib.POFile method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{api:polib.POFile.translated_entries}}
\pysigstartsignatures
\pysiglinewithargsret
{\sphinxbfcode{\sphinxupquote{translated\_entries}}}
{}
{}
\pysigstopsignatures
\sphinxAtStartPar
Convenience method that returns the list of translated entries.

\end{fulllineitems}

\index{untranslated\_entries() (polib.POFile method)@\spxentry{untranslated\_entries()}\spxextra{polib.POFile method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{api:polib.POFile.untranslated_entries}}
\pysigstartsignatures
\pysiglinewithargsret
{\sphinxbfcode{\sphinxupquote{untranslated\_entries}}}
{}
{}
\pysigstopsignatures
\sphinxAtStartPar
Convenience method that returns the list of untranslated entries.

\end{fulllineitems}


\end{fulllineitems}



\section{The \sphinxstyleliteralintitle{\sphinxupquote{MOFile}} class}
\label{\detokenize{api:the-mofile-class}}\index{MOFile (class in polib)@\spxentry{MOFile}\spxextra{class in polib}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{api:polib.MOFile}}
\pysigstartsignatures
\pysiglinewithargsret
{\sphinxbfcode{\sphinxupquote{class\DUrole{w}{ }}}\sphinxcode{\sphinxupquote{polib.}}\sphinxbfcode{\sphinxupquote{MOFile}}}
{\sphinxparam{\DUrole{o}{*}\DUrole{n}{args}}\sphinxparamcomma \sphinxparam{\DUrole{o}{**}\DUrole{n}{kwargs}}}
{}
\pysigstopsignatures
\sphinxAtStartPar
Mo file reader/writer.
This class inherits the \sphinxcode{\sphinxupquote{\_BaseFile}} class and, by
extension, the python \sphinxcode{\sphinxupquote{list}} type.
\index{fuzzy\_entries() (polib.MOFile method)@\spxentry{fuzzy\_entries()}\spxextra{polib.MOFile method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{api:polib.MOFile.fuzzy_entries}}
\pysigstartsignatures
\pysiglinewithargsret
{\sphinxbfcode{\sphinxupquote{fuzzy\_entries}}}
{}
{}
\pysigstopsignatures
\sphinxAtStartPar
Convenience method to keep the same interface with POFile instances.

\end{fulllineitems}

\index{obsolete\_entries() (polib.MOFile method)@\spxentry{obsolete\_entries()}\spxextra{polib.MOFile method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{api:polib.MOFile.obsolete_entries}}
\pysigstartsignatures
\pysiglinewithargsret
{\sphinxbfcode{\sphinxupquote{obsolete\_entries}}}
{}
{}
\pysigstopsignatures
\sphinxAtStartPar
Convenience method to keep the same interface with POFile instances.

\end{fulllineitems}

\index{percent\_translated() (polib.MOFile method)@\spxentry{percent\_translated()}\spxextra{polib.MOFile method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{api:polib.MOFile.percent_translated}}
\pysigstartsignatures
\pysiglinewithargsret
{\sphinxbfcode{\sphinxupquote{percent\_translated}}}
{}
{}
\pysigstopsignatures
\sphinxAtStartPar
Convenience method to keep the same interface with POFile instances.

\end{fulllineitems}

\index{save() (polib.MOFile method)@\spxentry{save()}\spxextra{polib.MOFile method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{api:polib.MOFile.save}}
\pysigstartsignatures
\pysiglinewithargsret
{\sphinxbfcode{\sphinxupquote{save}}}
{\sphinxparam{\DUrole{n}{fpath}\DUrole{o}{=}\DUrole{default_value}{None}}}
{}
\pysigstopsignatures
\sphinxAtStartPar
Saves the mofile to \sphinxcode{\sphinxupquote{fpath}}.

\sphinxAtStartPar
Keyword argument:
\begin{description}
\sphinxlineitem{\sphinxcode{\sphinxupquote{fpath}}}
\sphinxAtStartPar
string, full or relative path to the file.

\end{description}

\end{fulllineitems}

\index{save\_as\_pofile() (polib.MOFile method)@\spxentry{save\_as\_pofile()}\spxextra{polib.MOFile method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{api:polib.MOFile.save_as_pofile}}
\pysigstartsignatures
\pysiglinewithargsret
{\sphinxbfcode{\sphinxupquote{save\_as\_pofile}}}
{\sphinxparam{\DUrole{n}{fpath}}}
{}
\pysigstopsignatures
\sphinxAtStartPar
Saves the mofile as a pofile to \sphinxcode{\sphinxupquote{fpath}}.

\sphinxAtStartPar
Keyword argument:
\begin{description}
\sphinxlineitem{\sphinxcode{\sphinxupquote{fpath}}}
\sphinxAtStartPar
string, full or relative path to the file.

\end{description}

\end{fulllineitems}

\index{translated\_entries() (polib.MOFile method)@\spxentry{translated\_entries()}\spxextra{polib.MOFile method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{api:polib.MOFile.translated_entries}}
\pysigstartsignatures
\pysiglinewithargsret
{\sphinxbfcode{\sphinxupquote{translated\_entries}}}
{}
{}
\pysigstopsignatures
\sphinxAtStartPar
Convenience method to keep the same interface with POFile instances.

\end{fulllineitems}

\index{untranslated\_entries() (polib.MOFile method)@\spxentry{untranslated\_entries()}\spxextra{polib.MOFile method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{api:polib.MOFile.untranslated_entries}}
\pysigstartsignatures
\pysiglinewithargsret
{\sphinxbfcode{\sphinxupquote{untranslated\_entries}}}
{}
{}
\pysigstopsignatures
\sphinxAtStartPar
Convenience method to keep the same interface with POFile instances.

\end{fulllineitems}


\end{fulllineitems}



\section{The \sphinxstyleliteralintitle{\sphinxupquote{POEntry}} class}
\label{\detokenize{api:the-poentry-class}}\index{POEntry (class in polib)@\spxentry{POEntry}\spxextra{class in polib}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{api:polib.POEntry}}
\pysigstartsignatures
\pysiglinewithargsret
{\sphinxbfcode{\sphinxupquote{class\DUrole{w}{ }}}\sphinxcode{\sphinxupquote{polib.}}\sphinxbfcode{\sphinxupquote{POEntry}}}
{\sphinxparam{\DUrole{o}{*}\DUrole{n}{args}}\sphinxparamcomma \sphinxparam{\DUrole{o}{**}\DUrole{n}{kwargs}}}
{}
\pysigstopsignatures
\sphinxAtStartPar
Represents a po file entry.
\index{merge() (polib.POEntry method)@\spxentry{merge()}\spxextra{polib.POEntry method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{api:polib.POEntry.merge}}
\pysigstartsignatures
\pysiglinewithargsret
{\sphinxbfcode{\sphinxupquote{merge}}}
{\sphinxparam{\DUrole{n}{other}}}
{}
\pysigstopsignatures
\sphinxAtStartPar
Merge the current entry with the given pot entry.

\end{fulllineitems}

\index{translated() (polib.POEntry method)@\spxentry{translated()}\spxextra{polib.POEntry method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{api:polib.POEntry.translated}}
\pysigstartsignatures
\pysiglinewithargsret
{\sphinxbfcode{\sphinxupquote{translated}}}
{}
{}
\pysigstopsignatures
\sphinxAtStartPar
Returns \sphinxcode{\sphinxupquote{True}} if the entry has been translated or \sphinxcode{\sphinxupquote{False}}
otherwise.

\end{fulllineitems}


\end{fulllineitems}



\section{The \sphinxstyleliteralintitle{\sphinxupquote{MOEntry}} class}
\label{\detokenize{api:the-moentry-class}}\index{MOEntry (class in polib)@\spxentry{MOEntry}\spxextra{class in polib}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{api:polib.MOEntry}}
\pysigstartsignatures
\pysiglinewithargsret
{\sphinxbfcode{\sphinxupquote{class\DUrole{w}{ }}}\sphinxcode{\sphinxupquote{polib.}}\sphinxbfcode{\sphinxupquote{MOEntry}}}
{\sphinxparam{\DUrole{o}{*}\DUrole{n}{args}}\sphinxparamcomma \sphinxparam{\DUrole{o}{**}\DUrole{n}{kwargs}}}
{}
\pysigstopsignatures
\sphinxAtStartPar
Represents a mo file entry.

\end{fulllineitems}


\sphinxstepscope


\chapter{Contributing to polib}
\label{\detokenize{contributing:contributing-to-polib}}\label{\detokenize{contributing:contributing}}\label{\detokenize{contributing::doc}}
\sphinxAtStartPar
You are very welcome to contribute to the project!
The bugtracker, wiki and mercurial repository can be found at the
\sphinxhref{https://github.com/izimobil/polib/}{project’s page}.

\sphinxAtStartPar
New releases are also published at the
\sphinxhref{https://pypi.org/project/polib/}{“cheeseshop” (PyPI)}.


\section{How to contribute}
\label{\detokenize{contributing:how-to-contribute}}
\sphinxAtStartPar
There are various possibilities to get involved, for example you can:
\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxhref{https://github.com/izimobil/polib/issues/new/}{Report bugs}
preferably with patches if you can

\item {} 
\sphinxAtStartPar
Enhance this \sphinxhref{https://github.com/izimobil/polib/tree/master/docs/}{documentation}

\item {} 
\sphinxAtStartPar
\sphinxhref{https://github.com/izimobil/polib/}{Fork the code}, implement new
features, test and send a pull request

\end{itemize}


\section{Running the test suite}
\label{\detokenize{contributing:running-the-test-suite}}
\sphinxAtStartPar
To run the tests, just type the following on a terminal:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYGZdl{} cd /path/to/polib/
\PYGZdl{} ./runtests.sh
\end{sphinxVerbatim}

\sphinxAtStartPar
You can also use tox:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYGZdl{} cd /path/to/polib/
\PYGZdl{} pip install tox
\PYGZdl{} tox
\end{sphinxVerbatim}

\sphinxAtStartPar
If you want to generate coverage information:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYGZdl{} pip install coverage
\PYGZdl{} ./runtests.sh
\PYGZdl{} coverage html
\end{sphinxVerbatim}

\sphinxstepscope


\chapter{Projects using polib}
\label{\detokenize{projects:projects-using-polib}}\label{\detokenize{projects:projects}}\label{\detokenize{projects::doc}}
\sphinxAtStartPar
polib is used by many opensource projects, here are some of them:
\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxhref{http://mercurial.selenic.com}{Mercurial}

\item {} 
\sphinxAtStartPar
\sphinxhref{http://www.transifex.net/}{Transifex}

\item {} 
\sphinxAtStartPar
\sphinxhref{https://translations.launchpad.net/}{Launchpad ubuntu translator tools}

\item {} 
\sphinxAtStartPar
\sphinxhref{http://code.google.com/p/django-rosetta/}{Django\sphinxhyphen{}rosetta}

\item {} 
\sphinxAtStartPar
\sphinxhref{http://www.open-ils.org/}{The evergreen library system}

\item {} 
\sphinxAtStartPar
\sphinxhref{http://qooxdoo.org/}{Qooxdoo}

\item {} 
\sphinxAtStartPar
\sphinxhref{http://www.lictionary.in/}{Lictionary}

\item {} 
\sphinxAtStartPar
\sphinxhref{https://github.com/sebastian-software/jasy}{Jasy \sphinxhyphen{} Web Tooling Framework}

\end{itemize}

\sphinxAtStartPar
If you are using polib and wish to be listed here (or not)
\sphinxhref{mailto:izimobil@gmail.com}{let me know}.



\renewcommand{\indexname}{Index}
\printindex
\end{document}