cmdline.txt 6.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182
  1. .. -*- mode: rst; encoding: utf-8 -*-
  2. ======================
  3. Command-Line Interface
  4. ======================
  5. Babel includes a command-line interface for working with message catalogs,
  6. similar to the various GNU ``gettext`` tools commonly available on Linux/Unix
  7. systems.
  8. .. contents:: Contents
  9. :depth: 2
  10. .. sectnum::
  11. When properly installed, Babel provides a script called ``pybabel``::
  12. $ pybabel --help
  13. usage: pybabel command [options] [args]
  14. options:
  15. --version show program's version number and exit
  16. -h, --help show this help message and exit
  17. --list-locales print all known locales and exit
  18. -v, --verbose print as much as possible
  19. -q, --quiet print as little as possible
  20. commands:
  21. compile compile message catalogs to MO files
  22. extract extract messages from source files and generate a POT file
  23. init create new message catalogs from a POT file
  24. update update existing message catalogs from a POT file
  25. The ``pybabel`` script provides a number of sub-commands that do the actual
  26. work. Those sub-commands are described below.
  27. compile
  28. =======
  29. The ``compile`` sub-command can be used to compile translation catalogs into
  30. binary MO files::
  31. $ pybabel compile --help
  32. usage: pybabel compile [options]
  33. compile message catalogs to MO files
  34. options:
  35. -h, --help show this help message and exit
  36. -D DOMAIN, --domain=DOMAIN
  37. domain of MO and PO files (default 'messages')
  38. -d DIR, --directory=DIR
  39. base directory of catalog files
  40. -l LOCALE, --locale=LOCALE
  41. locale of the catalog
  42. -i FILE, --input-file=FILE
  43. name of the input file
  44. -o FILE, --output-file=FILE
  45. name of the output file (default
  46. '<output_dir>/<locale>/LC_MESSAGES/<domain>.mo')
  47. -f, --use-fuzzy also include fuzzy translations (default False)
  48. --statistics print statistics about translations
  49. If ``directory`` is specified, but ``output-file`` is not, the default filename
  50. of the output file will be::
  51. <directory>/<locale>/LC_MESSAGES/<domain>.mo
  52. If neither the ``input_file`` nor the ``locale`` option is set, this command
  53. looks for all catalog files in the base directory that match the given domain,
  54. and compiles each of them to MO files in the same directory.
  55. extract
  56. =======
  57. The ``extract`` sub-command can be used to extract localizable messages from
  58. a collection of source files::
  59. $ pybabel extract --help
  60. usage: pybabel extract [options] dir1 <dir2> ...
  61. extract messages from source files and generate a POT file
  62. options:
  63. -h, --help show this help message and exit
  64. --charset=CHARSET charset to use in the output (default "utf-8")
  65. -k KEYWORDS, --keyword=KEYWORDS
  66. keywords to look for in addition to the defaults. You
  67. can specify multiple -k flags on the command line.
  68. --no-default-keywords
  69. do not include the default keywords
  70. -F MAPPING_FILE, --mapping=MAPPING_FILE
  71. path to the extraction mapping file
  72. --no-location do not include location comments with filename and
  73. line number
  74. --omit-header do not include msgid "" entry in header
  75. -o OUTPUT, --output=OUTPUT
  76. path to the output POT file
  77. -w WIDTH, --width=WIDTH
  78. set output line width (default 76)
  79. --no-wrap do not break long message lines, longer than the
  80. output line width, into several lines
  81. --sort-output generate sorted output (default False)
  82. --sort-by-file sort output by file location (default False)
  83. --msgid-bugs-address=EMAIL@ADDRESS
  84. set report address for msgid
  85. --copyright-holder=COPYRIGHT_HOLDER
  86. set copyright holder in output
  87. -c TAG, --add-comments=TAG
  88. place comment block with TAG (or those preceding
  89. keyword lines) in output file. One TAG per argument
  90. call
  91. init
  92. ====
  93. The `init` sub-command creates a new translations catalog based on a PO
  94. template file::
  95. $ pybabel init --help
  96. usage: pybabel init [options]
  97. create new message catalogs from a POT file
  98. options:
  99. -h, --help show this help message and exit
  100. -D DOMAIN, --domain=DOMAIN
  101. domain of PO file (default 'messages')
  102. -i FILE, --input-file=FILE
  103. name of the input file
  104. -d DIR, --output-dir=DIR
  105. path to output directory
  106. -o FILE, --output-file=FILE
  107. name of the output file (default
  108. '<output_dir>/<locale>/LC_MESSAGES/<domain>.po')
  109. -l LOCALE, --locale=LOCALE
  110. locale for the new localized catalog
  111. update
  112. ======
  113. The `update` sub-command updates an existing new translations catalog based on
  114. a PO template file::
  115. $ pybabel update --help
  116. usage: pybabel update [options]
  117. update existing message catalogs from a POT file
  118. options:
  119. -h, --help show this help message and exit
  120. -D DOMAIN, --domain=DOMAIN
  121. domain of PO file (default 'messages')
  122. -i FILE, --input-file=FILE
  123. name of the input file
  124. -d DIR, --output-dir=DIR
  125. path to output directory
  126. -o FILE, --output-file=FILE
  127. name of the output file (default
  128. '<output_dir>/<locale>/LC_MESSAGES/<domain>.po')
  129. -l LOCALE, --locale=LOCALE
  130. locale of the translations catalog
  131. --ignore-obsolete do not include obsolete messages in the output
  132. (default False)
  133. -N, --no-fuzzy-matching
  134. do not use fuzzy matching (default False)
  135. --previous keep previous msgids of translated messages (default
  136. False)
  137. If ``output_dir`` is specified, but ``output-file`` is not, the default
  138. filename of the output file will be::
  139. <directory>/<locale>/LC_MESSAGES/<domain>.mo
  140. If neither the ``output_file`` nor the ``locale`` option is set, this command
  141. looks for all catalog files in the base directory that match the given domain,
  142. and updates each of them.