.. -*- mode: rst; encoding: utf-8 -*-

======================
Command-Line Interface
======================

Babel includes a command-line interface for working with message catalogs,
similar to the various GNU ``gettext`` tools commonly available on Linux/Unix
systems.


.. contents:: Contents
   :depth: 2
.. sectnum::


When properly installed, Babel provides a script called ``pybabel``::

    $ pybabel --help
    usage: pybabel subcommand [options] [args]

    options:
      --version             show program's version number and exit
      -h, --help            show this help message and exit

    subcommands:
      extract   extract messages from source files and generate a POT file
      init      create new message catalogs from a template

The ``pybabel`` script provides a number of sub-commands that do the actual
work. Those sub-commands are described below.


extract
=======

The ``extract`` sub-command can be used to extract localizable messages from
a collection of source files::

    $ pybabel extract --help
    usage: pybabel extract [options] dir1 <dir2> ...
    
    extract messages from source files and generate a POT file
    
    options:
      -h, --help            show this help message and exit
      --charset=CHARSET     charset to use in the output
      -k KEYWORDS, --keyword=KEYWORDS
                            keywords to look for in addition to the defaults. You
                            can specify multiple -k flags on the command line.
      --no-default-keywords
                            do not include the default keywords
      -F MAPPING_FILE, --mapping=MAPPING_FILE
                            path to the extraction mapping file
      --no-location         do not include location comments with filename and
                            line number
      --omit-header         do not include msgid "" entry in header
      -o OUTPUT, --output=OUTPUT
                            path to the output POT file
      -w WIDTH, --width=WIDTH
                            set output line width (default 76)
      --no-wrap             do not break long message lines, longer than the
                            output line width, into several lines
      --sort-output         generate sorted output (default False)
      --sort-by-file        sort output by file location (default False)
      --msgid-bugs-address=EMAIL@ADDRESS
                            set report address for msgid
      --copyright-holder=COPYRIGHT_HOLDER
                            set copyright holder in output
      -c TAG, --add-comments=TAG
                            place comment block with TAG (or those preceding
                            keyword lines) in output file. One TAG per argument
                            call


init
====

The `init` sub-command creates a new translations catalog based on a PO
template file::

    $ pybabel init --help
    usage: pybabel init [options] 
    
    create new message catalogs from a template
    
    options:
    -h, --help      show this help message and exit
    -D DOMAIN, --domain=DOMAIN
                    domain of PO file (defaults to lower-cased project
                    name)
    -i INPUT_FILE, --input-file=INPUT_FILE
                    name of the input file
    -d OUTPUT_DIR, --output-dir=OUTPUT_DIR
                    path to output directory
    -o OUTPUT_FILE, --output-file=OUTPUT_FILE
                    name of the output file (default
                    '<output_dir>/<locale>/<domain>.po')
    -l LOCALE, --locale=LOCALE
                    locale for the new localized catalog
    --first-author=FIRST_AUTHOR_NAME
                    name of first author
    --first-author-email=FIRST_AUTHOR_EMAIL
                    email of first author
    --project-name=NAME   the project name
    --project-version=VERSION
                    the project version