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