.. -*- 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 ``babel``::

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

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

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

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


compile
=======

The ``compile`` sub-command can be used to compile translation catalogs into
binary MO files::

    $ babel compile --help
    usage: babel compile [options] 
    
    compile message catalogs to MO files
    
    options:
      -h, --help            show this help message and exit
      -D DOMAIN, --domain=DOMAIN
                            domain of MO and PO files (default 'messages')
      -d DIR, --directory=DIR
                            base directory of catalog files
      -l LOCALE, --locale=LOCALE
                            locale of the catalog
      -i FILE, --input-file=FILE
                            name of the input file
      -o FILE, --output-file=FILE
                            name of the output file (default
                            '<output_dir>/<locale>/LC_MESSAGES/<domain>.mo')
      -f, --use-fuzzy       also include fuzzy translations (default False)

If ``directory`` is specified, but ``output-file`` is not, the default filename
of the output file will be::

    <directory>/<locale>/LC_MESSAGES/<domain>.mo

If neither the ``input_file`` nor the ``locale`` option is set, this command
looks for all catalog files in the base directory that match the given domain,
and compiles each of them to MO files in the same directory.



extract
=======

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

    $ babel extract --help
    usage: babel 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::

    $ babel init --help
    usage: babel 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