cmdline.rst 6.5 KB

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