Fix MergeCatalog options and update docs

Author: soft-suroleb

babel/messages/frontend.py

@@ -1025,30 +1025,30 @@ def run(self):
 
 
 class MergeCatalog(CommandMixin):
-    description='updates translation PO file by merging them with updated template POT file with using compendium'
-    user_options=[
-        ('input-files', None, 'def.po (obsolete translations) ref.pot (actual template)'),
+    description = 'update a PO file by merging it with a newer POT template, optionally using a compendium'
+    user_options = [
+        ('input-files', None, 'exactly two input files: def.po (obsolete translations); ref.pot (current template)'),
         ('compendium=', 'C', 'additional library of message translations, may be specified more than once'),
-        ('compendium-overwrite', '', 'overwrite mode of compendium'),
-        ('no-compendium-comment', '', ''),
-        ('update', 'U', 'pdate def.po, do nothing if def.po already up to date'),
+        ('compendium-overwrite', None, 'overwrite existing translations with compendium entries'),
+        ('no-compendium-comment', None, 'do not add a comment for translations taken from a compendium'),
+        ('update', 'U', 'update def.po, do nothing if def.po already up to date'),
         ('output-file=', 'o', 'write output to specified file, the results are written '
                               'to standard output if no output file is specified'),
         ('backup', None, 'make a backup of def.po'),
-        ('suffix=', None, 'override the usual backup suffix'),
+        ('suffix=', None, 'use SUFFIX as backup suffix instead of ~ (tilde)'),
         ('no-fuzzy-matching', 'N', 'do not use fuzzy matching'),
-        ('no-location', None, 'suppress \'#: filename:line\' lines'),
-        ('width=', 'w', 'set output page width'),
+        ('no-location', None, 'do not include location comments with filename and line number'),
+        ('width=', 'w', 'set output line width (default 76)'),
         ('no-wrap', None, 'do not break long message lines, longer '
-                          'than the output page width, into several lines'),
+                          'than the output line width, into several lines'),
         ('sort-output', 's', 'generate sorted output'),
         ('sort-by-file', 'F', 'sort output by file location'),
     ]
 
     as_args = 'input-files'
 
     multiple_value_options = (
-        'compendium'
+        'compendium',
     )
 
     boolean_options = [
@@ -1081,9 +1081,11 @@ def initialize_options(self):
 
     def finalize_options(self):
         if not self.input_files or len(self.input_files) != 2:
-            raise OptionError('must be two po files')
+            raise OptionError(
+                f'exactly two input files are required (def.po and ref.pot), got: {self.input_files!r}'
+            )
         if not self.output_file and not self.update:
-            raise OptionError('you must specify the output file or update existing')
+            raise OptionError('you must specify the output file or use --update')
 
         if self.no_wrap and self.width:
             raise OptionError("'--no-wrap' and '--width' are mutually exclusive")
@@ -1092,8 +1094,10 @@ def finalize_options(self):
         elif self.width is not None:
             self.width = int(self.width)
 
-    def _get_message_from_compendium(self, compendium):
-        for file_path in compendium:
+    def _get_messages_from_compendiums(self, compendium_paths):
+        if not compendium_paths:
+            return
+        for file_path in compendium_paths:
             with open(file_path, 'r') as pofile:
                 catalog = read_po(pofile)
                 for message in catalog:
@@ -1111,19 +1115,17 @@ def run(self):
             no_fuzzy_matching=self.no_fuzzy_matching
         )
 
-        if self.compendium:
-            for message, compendium_path in self._get_message_from_compendium(self.compendium):
-                current = catalog[message.id]
-                if message.id in catalog and (not current.string or current.fuzzy or self.compendium_overwrite):
-                    if self.compendium_overwrite and not current.fuzzy and current.string:
-                        catalog.obsolete[message.id] = current.clone()
+        for message, compendium_path in self._get_messages_from_compendiums(self.compendium):
+            if (current := catalog.get(message.id)) and (not current.string or current.fuzzy or self.compendium_overwrite):
+                if self.compendium_overwrite and not current.fuzzy and current.string:
+                    catalog.obsolete[message.id] = current.clone()
 
-                    current.string = message.string
-                    if current.fuzzy:
-                        current.flags.remove('fuzzy')
+                current.string = message.string
+                if current.fuzzy:
+                    current.flags.remove('fuzzy')
 
-                    if not self.no_compendium_comment:
-                        current.auto_comments.append(compendium_path)
+                if not self.no_compendium_comment:
+                    current.auto_comments.append(compendium_path)
 
         catalog.fuzzy = any(message.fuzzy for message in catalog)
         output_path = def_file if self.update else self.output_file

docs/cmdline.rst

@@ -251,11 +251,9 @@ and updates each of them.
 concat
 ======
 
-The `concat` command merges multiple PO files into a single one. If a message has
+The ``concat`` command merges multiple PO files into 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::
+marked with a conflict comment and the message itself is marked with a ``fuzzy`` flag::
 
     $ pybabel concat --help
     Usage: pybabel concat [options] <input-files>
@@ -265,79 +263,73 @@ and the message itself is marked with a `fuzzy` flag::
     Options:
       -h, --help            show this help message and exit
       -o OUTPUT_FILE, --output-file=OUTPUT_FILE
-                            write output to specified file
+                            write output to specified file, the results are written
+                            to standard output if no output file is specified or if it is '-'
       --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
+      -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
+      --no-location         do not include location comments with filename and line number
       -w WIDTH, --width=WIDTH
-                            set output page width
+                            set output line width (default 76)
       --no-wrap             do not break long message lines, longer than
-                            the output page width, into several lines
+                            the output line 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::
+The ``merge`` command allows updating files, optionally using a compendium as a translation memory::
 
-    $ pybabel concat --help
+    $ pybabel merge --help
     Usage: pybabel merge [options] <input-files>
 
-    updates translation PO file by merging them with updated template
-    POT file with using compendium
+    update a PO file by merging it with a newer POT template, optionally using a 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
+                            overwrite existing translations with compendium entries
       --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,
+                            do not add a comment for translations taken from a 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 '~')
+      --suffix=SUFFIX       use SUFFIX as backup suffix instead of ~ (tilde)
       -N, --no-fuzzy-matching
                             do not use fuzzy matching
-      --no-location         suppress '#: filename:line' lines'
+      --no-location         do not include location comments with filename and line number
       -w WIDTH, --width=WIDTH
-                            set output page width
+                            set output line width (default 76)
       --no-wrap             do not break long message lines, longer
-                            than the output page width, into several lines
+                            than the output line 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
+      -F, --sort-by-file    sort output by file location
 
 The ``input-files`` option accepts exactly two arguments: a file with obsolete translations, and
 the current template file for updating translations.
 
 The ``compendium`` option can be specified multiple times to use several compendiums.
+The compendium can be used in two modes:
 
-The ``backup`` option is used to create a backup copy of the def.po file, which contains
-obsolete translations.
+- Default mode: 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.
 
+The ``backup`` option is used to create a backup copy of the def.po file before updating it.
 The ``suffix`` option allows you to specify a custom suffix for the backup file (defaulting to ``~``).
 
-pybable concat and merge usage scenarios
-======
+concat and merge usage scenarios
+=================================
 
 1. Merging Multiple PO Files (`concat`)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~