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@191: When properly installed, Babel provides a script called ``pybabel``::
cmlenz@4: 
cmlenz@191:     $ pybabel --help
cmlenz@191:     usage: pybabel subcommand [options] [args]
cmlenz@4: 
cmlenz@4:     options:
cmlenz@179:       --version   show program's version number and exit
cmlenz@179:       -h, --help  show this help message and exit
cmlenz@54: 
cmlenz@75:     subcommands:
cmlenz@179:       compile     compile message catalogs to MO files
cmlenz@179:       extract     extract messages from source files and generate a POT file
cmlenz@183:       init        create new message catalogs from a POT file
cmlenz@183:       update      update existing message catalogs from a POT file
cmlenz@75: 
cmlenz@191: The ``pybabel`` script provides a number of sub-commands that do the actual
cmlenz@191: work. Those sub-commands are described below.
cmlenz@54: 
cmlenz@54: 
cmlenz@179: compile
cmlenz@179: =======
cmlenz@179: 
cmlenz@179: The ``compile`` sub-command can be used to compile translation catalogs into
cmlenz@179: binary MO files::
cmlenz@179: 
cmlenz@191:     $ pybabel compile --help
cmlenz@191:     usage: pybabel compile [options] 
cmlenz@179:     
cmlenz@179:     compile message catalogs to MO files
cmlenz@179:     
cmlenz@179:     options:
cmlenz@179:       -h, --help            show this help message and exit
cmlenz@179:       -D DOMAIN, --domain=DOMAIN
cmlenz@179:                             domain of MO and PO files (default 'messages')
cmlenz@179:       -d DIR, --directory=DIR
cmlenz@179:                             base directory of catalog files
cmlenz@179:       -l LOCALE, --locale=LOCALE
cmlenz@179:                             locale of the catalog
cmlenz@179:       -i FILE, --input-file=FILE
cmlenz@179:                             name of the input file
cmlenz@179:       -o FILE, --output-file=FILE
cmlenz@179:                             name of the output file (default
cmlenz@179:                             '<output_dir>/<locale>/LC_MESSAGES/<domain>.mo')
cmlenz@179:       -f, --use-fuzzy       also include fuzzy translations (default False)
cmlenz@179: 
cmlenz@179: If ``directory`` is specified, but ``output-file`` is not, the default filename
cmlenz@179: of the output file will be::
cmlenz@179: 
cmlenz@179:     <directory>/<locale>/LC_MESSAGES/<domain>.mo
cmlenz@179: 
cmlenz@179: If neither the ``input_file`` nor the ``locale`` option is set, this command
cmlenz@179: looks for all catalog files in the base directory that match the given domain,
cmlenz@179: and compiles each of them to MO files in the same directory.
cmlenz@179: 
cmlenz@179: 
cmlenz@179: 
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@191:     $ pybabel extract --help
cmlenz@191:     usage: pybabel 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@191:     $ pybabel init --help
cmlenz@191:     usage: pybabel init [options] 
cmlenz@75:     
cmlenz@183:     create new message catalogs from a POT file
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
cmlenz@183: 
cmlenz@183: 
cmlenz@183: update
cmlenz@183: ======
cmlenz@183: 
cmlenz@183: The `update` sub-command updates an existing new translations catalog based on
cmlenz@183: a PO template file::
cmlenz@183: 
cmlenz@191:     $ pybabel update --help
cmlenz@191:     usage: pybabel update [options] 
cmlenz@183:     
cmlenz@183:     update existing message catalogs from a POT file
cmlenz@183:     
cmlenz@183:     options:
cmlenz@183:       -h, --help            show this help message and exit
cmlenz@183:       -D DOMAIN, --domain=DOMAIN
cmlenz@183:                             domain of PO file (default 'messages')
cmlenz@183:       -i FILE, --input-file=FILE
cmlenz@183:                             name of the input file
cmlenz@183:       -d DIR, --output-dir=DIR
cmlenz@183:                             path to output directory
cmlenz@183:       -o FILE, --output-file=FILE
cmlenz@183:                             name of the output file (default
cmlenz@183:                             '<output_dir>/<locale>/LC_MESSAGES/<domain>.po')
cmlenz@183:       -l LOCALE, --locale=LOCALE
cmlenz@183:                             locale of the translations catalog
cmlenz@193:       --ignore-obsolete     do not include obsolete messages in the output
cmlenz@193:                             (default False)
cmlenz@183: 
cmlenz@183: If ``output_dir`` is specified, but ``output-file`` is not, the default
cmlenz@183: filename of the output file will be::
cmlenz@183: 
cmlenz@183:     <directory>/<locale>/LC_MESSAGES/<domain>.mo
cmlenz@183: 
cmlenz@183: If neither the ``output_file`` nor the ``locale`` option is set, this command
cmlenz@183: looks for all catalog files in the base directory that match the given domain,
cmlenz@183: and updates each of them.