cmlenz@2: .. -*- mode: rst; encoding: utf-8 -*-
cmlenz@2: 
cmlenz@2: ======================
cmlenz@2: Command-Line Interface
cmlenz@2: ======================
cmlenz@2: 
cmlenz@2: Babel includes a command-line interface for working with message catalogs,
cmlenz@52: similar to the various GNU ``gettext`` tools commonly available on Linux/Unix
cmlenz@2: systems.
cmlenz@2: 
cmlenz@2: 
cmlenz@2: .. contents:: Contents
cmlenz@2:    :depth: 2
cmlenz@2: .. sectnum::
cmlenz@2: 
cmlenz@2: 
cmlenz@52: When properly installed, Babel provides a script called ``babel``::
cmlenz@2: 
cmlenz@52:     $ babel --help
cmlenz@52:     usage: babel subcommand [options] [args]
cmlenz@2: 
cmlenz@2:     options:
cmlenz@2:       --version             show program's version number and exit
cmlenz@2:       -h, --help            show this help message and exit
cmlenz@52: 
cmlenz@73:     subcommands:
cmlenz@73:       extract   extract messages from source files and generate a POT file
cmlenz@73:       init      create new message catalogs from a template
cmlenz@73: 
cmlenz@52: The ``babel`` script provides a number of sub-commands that do the actual work.
cmlenz@52: Those sub-commands are described below.
cmlenz@52: 
cmlenz@52: 
cmlenz@52: extract
cmlenz@52: =======
cmlenz@52: 
cmlenz@52: The ``extract`` sub-command can be used to extract localizable messages from
cmlenz@52: a collection of source files::
cmlenz@52: 
cmlenz@52:     $ babel extract --help
cmlenz@52:     usage: babel extract [options] dir1 <dir2> ...
cmlenz@77:     
cmlenz@77:     extract messages from source files and generate a POT file
cmlenz@77:     
cmlenz@52:     options:
cmlenz@52:       -h, --help            show this help message and exit
cmlenz@2:       --charset=CHARSET     charset to use in the output
cmlenz@2:       -k KEYWORDS, --keyword=KEYWORDS
cmlenz@2:                             keywords to look for in addition to the defaults. You
cmlenz@2:                             can specify multiple -k flags on the command line.
cmlenz@52:       --no-default-keywords
cmlenz@52:                             do not include the default keywords
cmlenz@52:       -F MAPPING_FILE, --mapping=MAPPING_FILE
cmlenz@52:                             path to the extraction mapping file
cmlenz@2:       --no-location         do not include location comments with filename and
cmlenz@2:                             line number
cmlenz@2:       --omit-header         do not include msgid "" entry in header
cmlenz@2:       -o OUTPUT, --output=OUTPUT
cmlenz@2:                             path to the output POT file
cmlenz@52:       -w WIDTH, --width=WIDTH
cmlenz@52:                             set output line width (default 76)
cmlenz@52:       --no-wrap             do not break long message lines, longer than the
cmlenz@52:                             output line width, into several lines
cmlenz@77:       --sort-output         generate sorted output (default False)
cmlenz@77:       --sort-by-file        sort output by file location (default False)
palgarvio@78:       --msgid-bugs-address=EMAIL@ADDRESS
palgarvio@78:                             set report address for msgid
palgarvio@79:       --copyright-holder=COPYRIGHT_HOLDER
palgarvio@79:                             set copyright holder in output
palgarvio@80:       -c TAG, --add-comments=TAG
palgarvio@80:                             place comment block with TAG (or those preceding
palgarvio@80:                             keyword lines) in output file. One TAG per argument
palgarvio@80:                             call
cmlenz@73: 
cmlenz@73: 
cmlenz@73: init
cmlenz@73: ====
cmlenz@73: 
cmlenz@73: The `init` sub-command creates a new translations catalog based on a PO
cmlenz@73: template file::
cmlenz@73: 
cmlenz@73:     $ babel init --help
cmlenz@73:     usage: babel init [options] 
cmlenz@73:     
cmlenz@73:     create new message catalogs from a template
cmlenz@73:     
cmlenz@73:     options:
cmlenz@73:     -h, --help      show this help message and exit
cmlenz@73:     -D DOMAIN, --domain=DOMAIN
cmlenz@73:                     domain of PO file (defaults to lower-cased project
cmlenz@73:                     name)
cmlenz@73:     -i INPUT_FILE, --input-file=INPUT_FILE
cmlenz@73:                     name of the input file
cmlenz@73:     -d OUTPUT_DIR, --output-dir=OUTPUT_DIR
cmlenz@73:                     path to output directory
cmlenz@73:     -o OUTPUT_FILE, --output-file=OUTPUT_FILE
cmlenz@73:                     name of the output file (default
cmlenz@73:                     '<output_dir>/<locale>/<domain>.po')
cmlenz@73:     -l LOCALE, --locale=LOCALE
cmlenz@73:                     locale for the new localized catalog
cmlenz@73:     --first-author=FIRST_AUTHOR_NAME
cmlenz@73:                     name of first author
cmlenz@73:     --first-author-email=FIRST_AUTHOR_EMAIL
cmlenz@73:                     email of first author
cmlenz@73:     --project-name=NAME   the project name
cmlenz@73:     --project-version=VERSION
cmlenz@73:                     the project version