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@189: When properly installed, Babel provides a script called ``pybabel``::
cmlenz@2: 
cmlenz@319:     $ pybabel --help 
cmlenz@319:     usage: pybabel command [options] [args]
cmlenz@2: 
cmlenz@2:     options:
cmlenz@319:       --version       show program's version number and exit
cmlenz@319:       -h, --help      show this help message and exit
cmlenz@319:       --list-locales  print all known locales and exit
cmlenz@319:       -v, --verbose   print as much as possible
cmlenz@319:       -q, --quiet     print as little as possible
cmlenz@52: 
cmlenz@319:     commands:
cmlenz@319:       compile  compile message catalogs to MO files
cmlenz@319:       extract  extract messages from source files and generate a POT file
cmlenz@319:       init     create new message catalogs from a POT file
cmlenz@319:       update   update existing message catalogs from a POT file
cmlenz@73: 
cmlenz@189: The ``pybabel`` script provides a number of sub-commands that do the actual
cmlenz@189: work. Those sub-commands are described below.
cmlenz@52: 
cmlenz@52: 
cmlenz@177: compile
cmlenz@177: =======
cmlenz@177: 
cmlenz@177: The ``compile`` sub-command can be used to compile translation catalogs into
cmlenz@177: binary MO files::
cmlenz@177: 
cmlenz@189:     $ pybabel compile --help
cmlenz@189:     usage: pybabel compile [options] 
cmlenz@319: 
cmlenz@177:     compile message catalogs to MO files
cmlenz@319: 
cmlenz@177:     options:
cmlenz@177:       -h, --help            show this help message and exit
cmlenz@177:       -D DOMAIN, --domain=DOMAIN
cmlenz@177:                             domain of MO and PO files (default 'messages')
cmlenz@177:       -d DIR, --directory=DIR
cmlenz@177:                             base directory of catalog files
cmlenz@177:       -l LOCALE, --locale=LOCALE
cmlenz@177:                             locale of the catalog
cmlenz@177:       -i FILE, --input-file=FILE
cmlenz@177:                             name of the input file
cmlenz@177:       -o FILE, --output-file=FILE
cmlenz@177:                             name of the output file (default
cmlenz@177:                             '<output_dir>/<locale>/LC_MESSAGES/<domain>.mo')
cmlenz@177:       -f, --use-fuzzy       also include fuzzy translations (default False)
cmlenz@319:       --statistics          print statistics about translations
cmlenz@177: 
cmlenz@177: If ``directory`` is specified, but ``output-file`` is not, the default filename
cmlenz@177: of the output file will be::
cmlenz@177: 
cmlenz@177:     <directory>/<locale>/LC_MESSAGES/<domain>.mo
cmlenz@177: 
cmlenz@177: If neither the ``input_file`` nor the ``locale`` option is set, this command
cmlenz@177: looks for all catalog files in the base directory that match the given domain,
cmlenz@177: and compiles each of them to MO files in the same directory.
cmlenz@177: 
cmlenz@177: 
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@189:     $ pybabel extract --help
cmlenz@189:     usage: pybabel extract [options] dir1 <dir2> ...
cmlenz@319: 
cmlenz@77:     extract messages from source files and generate a POT file
cmlenz@319: 
cmlenz@52:     options:
cmlenz@52:       -h, --help            show this help message and exit
cmlenz@319:       --charset=CHARSET     charset to use in the output (default "utf-8")
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@189:     $ pybabel init --help
cmlenz@189:     usage: pybabel init [options] 
cmlenz@319: 
cmlenz@181:     create new message catalogs from a POT file
cmlenz@319: 
cmlenz@73:     options:
cmlenz@319:       -h, --help            show this help message and exit
cmlenz@319:       -D DOMAIN, --domain=DOMAIN
cmlenz@319:                             domain of PO file (default 'messages')
cmlenz@319:       -i FILE, --input-file=FILE
cmlenz@319:                             name of the input file
cmlenz@319:       -d DIR, --output-dir=DIR
cmlenz@319:                             path to output directory
cmlenz@319:       -o FILE, --output-file=FILE
cmlenz@319:                             name of the output file (default
cmlenz@319:                             '<output_dir>/<locale>/LC_MESSAGES/<domain>.po')
cmlenz@319:       -l LOCALE, --locale=LOCALE
cmlenz@319:                             locale for the new localized catalog
cmlenz@181: 
cmlenz@181: 
cmlenz@181: update
cmlenz@181: ======
cmlenz@181: 
cmlenz@181: The `update` sub-command updates an existing new translations catalog based on
cmlenz@181: a PO template file::
cmlenz@181: 
cmlenz@189:     $ pybabel update --help
cmlenz@189:     usage: pybabel update [options] 
cmlenz@319: 
cmlenz@181:     update existing message catalogs from a POT file
cmlenz@319: 
cmlenz@181:     options:
cmlenz@181:       -h, --help            show this help message and exit
cmlenz@181:       -D DOMAIN, --domain=DOMAIN
cmlenz@181:                             domain of PO file (default 'messages')
cmlenz@181:       -i FILE, --input-file=FILE
cmlenz@181:                             name of the input file
cmlenz@181:       -d DIR, --output-dir=DIR
cmlenz@181:                             path to output directory
cmlenz@181:       -o FILE, --output-file=FILE
cmlenz@181:                             name of the output file (default
cmlenz@181:                             '<output_dir>/<locale>/LC_MESSAGES/<domain>.po')
cmlenz@181:       -l LOCALE, --locale=LOCALE
cmlenz@181:                             locale of the translations catalog
cmlenz@191:       --ignore-obsolete     do not include obsolete messages in the output
cmlenz@191:                             (default False)
cmlenz@319:       -N, --no-fuzzy-matching
cmlenz@319:                             do not use fuzzy matching (default False)
cmlenz@319:       --previous            keep previous msgids of translated messages (default
cmlenz@319:                             False)
cmlenz@181: 
cmlenz@181: If ``output_dir`` is specified, but ``output-file`` is not, the default
cmlenz@181: filename of the output file will be::
cmlenz@181: 
cmlenz@181:     <directory>/<locale>/LC_MESSAGES/<domain>.mo
cmlenz@181: 
cmlenz@181: If neither the ``output_file`` nor the ``locale`` option is set, this command
cmlenz@181: looks for all catalog files in the base directory that match the given domain,
cmlenz@181: and updates each of them.