Add info about pybable concat and pybabel merge into docs

Author: soft-suroleb

babel/messages/frontend.py

@@ -854,7 +854,7 @@ def run(self):
 
 
 class ConcatenateCatalog(CommandMixin):
-    description = 'concatenates and merges the specified PO files'
+    description = 'concatenates the specified PO files into single one'
     user_options = [
         ('input-files', None, 'input files'),
         ('output-file=', 'o', 'write output to specified file'),

docs/cmdline.rst

@@ -247,3 +247,92 @@ filename of the output file will be::
 If neither the ``output_file`` nor the ``locale`` option is set, this command
 looks for all catalog files in the base directory that match the given domain,
 and updates each of them.
+
+concat
+======
+
+The `concat` command merges multiple PO files into a single one. If a message has
+different translations in different PO files, the conflicting translations are
+marked with a conflict comment::
+    #-#-#-#-#  <file> (PROJECT VERSION)  #-#-#-#-#
+and the message itself is marked with a `fuzzy` flag::
+
+    $ pybabel concat --help
+    Usage: pybabel concat [options] <input-files>
+
+    concatenates the specified PO files into single one
+
+    Options:
+      -h, --help            show this help message and exit
+      -o OUTPUT_FILE, --output-file=OUTPUT_FILE
+                            write output to specified file
+      --less-than=NUMBER    print messages with less than this many
+                            definitions, defaults to infinite if not set
+      --more-than=NUMBER    print messages with more than this many
+                            definitions, defaults to 0 if not set
+      -u, unique            shorthand for --less-than=2, requests
+                            that only unique messages be printed
+      --use-first           use first available translation for each
+                            message, don't merge several translations
+      --no-location         do not write '#: filename:line' lines
+      -w WIDTH, --width=WIDTH
+                            set output page width
+      --no-wrap             do not break long message lines, longer than
+                            the output page width, into several lines
+      -s, --sort-output     generate sorted output
+      -F, --sort-by-file    sort output by file location
+
+merge
+======
+
+The `merge` command allows updating files using a compendium as a translation memory::
+
+    $ pybabel concat --help
+    Usage: pybabel merge [options] <input-files>
+
+    updates translation PO file by merging them with updated template
+    POT file with using compendium
+
+    Options:
+      -C COMPENDIUM_FILE, --compendium=COMPENDIUM_FILE
+                            additional library of message translations, may
+                            be specified more than once
+      --compendium-overwrite
+                            overwrite mode of compendium
+      --no-compendium-comment
+                            do not add a comment indicating that the message is
+                            taken from the compendium
+      -U, --update          update def.po, do nothing if def.po already up to date,
+      -o OUTPUT_FILE, --output-file=OUTPUT_FILE
+                            write output to specified file, the results are written
+                            to standard output if no output file is specified
+      --backup              make a backup of def.po
+      --suffix=SUFFIX       override the usual backup suffix (default '~')
+      -N, --no-fuzzy-matching
+                            do not use fuzzy matching
+      --no-location         suppress '#: filename:line' lines'
+      -w WIDTH, --width=WIDTH
+                            set output page width
+      --no-wrap             do not break long message lines, longer
+                            than the output page width, into several lines
+      -s, --sort-output     generate sorted output
+      -F --sort-by-file     sort output by file location
+
+The compendium can be used in two modes:
+- Default mode: the translations from the compendium are used
+  only if they are missing in the output file.
+
+- Compendium overwrite mode: when using the ``compendium-overwrite`` option, translations
+  from the compendium take priority and replace those in the output file. If a translation
+  is used from the compendium, a comment noting the source is added
+
+The ``input-files`` option includes def.po, a file with obsolete translations, and ref.pot,
+the current template file for updating translations.
+
+The ``compendium`` option can be specified multiple times to use several compendiums.
+
+The ``backup`` option is used to create a backup copy of the def.po file, which contains
+obsolete translations
+
+The ``suffix`` option allows you to specify a custom suffix for the backup file
+By default, a standard suffix ``~`` is appended to the backup file's name,