Fix PR issues

* Rename file_name to filename

* Adding fuzzy flag to message parameterized in 'add_conflict'

* Replace usage scenarious to cmdline.rst

* Rename to ConcatenateCatalog

Author: soft-suroleb

babel/messages/catalog.py

@@ -13,6 +13,7 @@
 import re
 import os
 from collections.abc import Iterable, Iterator
+from collections import defaultdict
 from copy import copy
 from difflib import SequenceMatcher
 from email import message_from_string
@@ -341,7 +342,7 @@ def _force_text(s: str | bytes, encoding: str = 'utf-8', errors: str = 'strict')
 
 class ConflictInfo(TypedDict):
     message: Message
-    file_name: str
+    filename: str
     project: str
     version: str
 
@@ -389,7 +390,7 @@ def __init__(
         self.locale = locale
         self._header_comment = header_comment
         self._messages: dict[str | tuple[str, str], Message] = {}
-        self._conflicts: dict[str | tuple[str, str], list[ConflictInfo]] = {}
+        self._conflicts: dict[str | tuple[str, str], list[ConflictInfo]] = defaultdict(list)
 
         self.project = project or 'PROJECT'
         self.version = version or 'VERSION'
@@ -756,18 +757,17 @@ def __setitem__(self, id: _MessageID, message: Message) -> None:
                     f"Expected sequence but got {type(message.string)}"
             self._messages[key] = message
 
-    def add_conflict(self, message: Message, file_name: str, project: str, version: str):
+    def add_conflict(self, message: Message, filename: str, project: str, version: str, fuzzy: bool = True):
         key = message.id
-        if key not in self._conflicts:
-            self._conflicts[key] = []
-
         self._conflicts[key].append({
             'message': message,
-            'file_name': file_name,
+            'filename': filename,
             'project': project,
             'version': version,
         })
-        message.flags |= {'fuzzy'}
+
+        if fuzzy:
+            message.flags |= {'fuzzy'}
 
     def add(
         self,

babel/messages/frontend.py

@@ -958,8 +958,8 @@ def run(self):
                     continue
 
                 if count > 1 and not self.use_first and diff_string_count > 1:
-                    file_name = os.path.basename(path)
-                    catalog.add_conflict(message, file_name, template.project, template.version)
+                    filename = os.path.basename(path)
+                    catalog.add_conflict(message, filename, template.project, template.version)
 
                 catalog[message.id] = message
 
@@ -1109,7 +1109,7 @@ class CommandLineInterface:
         'init': 'create new message catalogs from a POT file',
         'update': 'update existing message catalogs from a POT file',
         'concat': 'concatenates and merges the specified PO files',
-        'merge': 'combines two Uniforum-style PO files into one',
+        'merge': 'combines two PO files into one',
     }
 
     command_classes = {

babel/messages/pofile.py

@@ -653,7 +653,7 @@ def _format_conflict(key: str | tuple[str, str], conflicts: list[ConflictInfo],
         for conflict in conflicts:
             message = conflict['message']
             if message.context:
-                yield from _format_conflict_comment(conflict['file_name'], conflict['project'], conflict['version'], prefix=prefix)
+                yield from _format_conflict_comment(conflict['filename'], conflict['project'], conflict['version'], prefix=prefix)
                 yield f"{prefix}msgctxt {normalize(message.context, prefix=prefix, width=width)}\n"
 
         if isinstance(key, (list, tuple)):
@@ -665,7 +665,7 @@ def _format_conflict(key: str | tuple[str, str], conflicts: list[ConflictInfo],
 
         for conflict in conflicts:
             message = conflict['message']
-            yield from _format_conflict_comment(conflict['file_name'], conflict['project'], conflict['version'], prefix=prefix)
+            yield from _format_conflict_comment(conflict['filename'], conflict['project'], conflict['version'], prefix=prefix)
             if isinstance(key, (list, tuple)):
                 for idx in range(catalog.num_plurals):
                     try:

docs/cmdline.rst

@@ -326,13 +326,65 @@ The compendium can be used in two modes:
   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 ``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 ``backup`` option is used to create a backup copy of the def.po file, which contains
-obsolete translations
+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,
+The ``suffix`` option allows you to specify a custom suffix for the backup file (defaulting to ``~``).
+
+pybable concat and merge usage scenarios
+======
+
+1. Merging Multiple PO Files (`concat`)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Usage:**
+`pybabel concat [options] <po_files>`
+Suppose you manage a project with several PO files for the same language (for example, modules or plugins have their own translations), and you want to combine them into a single file for further work or for delivery to translators.
+
+**Example:**
+
+.. code-block:: shell
+
+    pybabel concat -o merged.po module1.po module2.po module3.po
+
+**Features:**
+
+- If the same string has different translations in different files, the resulting file for that string will include a special comment ``#-#-#-#-#  <file> (PROJECT VERSION)  #-#-#-#-#`` and the message will be marked with the ``fuzzy`` flag—this is useful for later manual conflict resolution.
+- You can keep only unique strings using the ``-u`` (`--less-than=2`) option.
+- Use `--use-first` to take only the first encountered translation for each string, skipping automatic merging of multiple options.
+- Output can be sorted alphabetically or by source file (options `-s`, `-F`).
+
+**Typical Use Case:**
+
+    A project has translations from different teams. Before releasing, you need to gather all translations into one file, resolve possible conflicts, and provide the finalized version to translators for review.
+
+
+2. Updating Translations with a Template and Compendium (`merge`)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Usage:**
+`pybabel merge [options] def.po ref.pot`
+You need to update an existing translation file (`def.po`) based on a new template (`ref.pot`), reusing translations from an additional translation memory (compendium).
+
+**Example:**
+
+.. code-block:: shell
+
+    pybabel merge -C my-compendium.po --backup def.po ref.pot
+
+**Features:**
+
+- The compendium (`-C`) allows you to pull translations from a shared translation memory. Multiple compendiums can be used.
+- By default, translations from the compendium are used only for new or missing entries in `def.po`.
+- The `--compendium-overwrite` option allows overwriting existing translations with those found in the compendium (helpful for terminology standardization).
+- When a translation from the compendium is used, a comment is automatically added (this can be disabled with `--no-compendium-comment`).
+- The `--backup` flag saves a backup copy of your file before updating (`~` suffix by default, configurable with `--suffix`).
+
+**Typical Use Case:**
+
+    After a release, a new translation template is provided. The team decides to enrich the translation by leveraging a common compendium in order to improve quality and unify terms. The merge command is run with the compendium and backup options enabled.