Update the CLI to use the translatable strings (59d73c8) - derivepassphrase.git

Update the CLI to use the translatable strings

Marco Ricci commited on 2024-12-30 23:45:01
Zeige 2 geänderte Dateien mit 1170 Einfügungen und 336 Löschungen.

We implement the translations in a deferred manner, via objects that
stringify to their correct translation.  Since `click` 8.1, help texts
are (mostly) stored first and processed only when the help page is
emitted.  Accordingly, this system can be adapted to support our
translatable strings: we need only ensure the help text is stringified
just before it is formatted and emitted.  This in turn can be achieved
by reimplementing the help page assembly and formatting in a custom
`click.Command` class, as has already been done to implement help/option
group support.  Once this is in place, it remains to exchange all inline
help texts with the corresponding translatable string, and adapt the
tests to the new messages.

While most of the changes are straightforward, some subtleties remain.

First, the help texts are now supplied as (separately translatable)
paragraphs to the `click.command` decorator, instead of being extracted
from the respective function docstring.  The docstrings in return have
been shortened down.

Second, since the new capabilities are implemented via custom
`click.Command`, `click.MultiCommand` and `click.Option` subclasses,
every option and command must derive from one of these classes.  This
necessitates the creation of an empty `StandardOption` class for options
without an option group, and making `_DefaultToVaultGroup` a subclass of
`CommandWithHelpGroups`.

Third, since the `click.Option` class actually processes its help text
eagerly, the subclass must hide the (non-string) help text from the
`click.Option` constructor and later restore it.

Finally, while the tests currently pass as before, they now implicitly
rely on *not* loading any translations.  Furthermore, there is no
mechanism in place with which to isolate the translation system from the
user's environment for testing purposes, nor is there a (controlled)
mechanism to test `derivepassphrase` under a different language.  Once
there are actual translations, future commits will need to establish
such a missing mechanism for translation loading/switching/forcing.

src/derivepassphrase/cli.py 78743d0..d1dca44
tests/test_derivepassphrase_cli.py 0085e5c..988d588

src/derivepassphrase/cli.py

Zeige Datei @ 59d73c8

@@ -41,6 +41,7 @@ from typing_extensions import (
 )
 
 import derivepassphrase as dpp
+from derivepassphrase import _cli_msg as _msg
 from derivepassphrase import _types, exporter, ssh_agent, vault
 
 if sys.version_info >= (3, 11):
@@ -63,14 +64,17 @@ __version__ = dpp.__version__
 
 __all__ = ('derivepassphrase',)
 
-PROG_NAME = 'derivepassphrase'
+PROG_NAME = _msg.PROG_NAME
 KEY_DISPLAY_LENGTH = 50
 
 # Error messages
 _INVALID_VAULT_CONFIG = 'Invalid vault config'
 _AGENT_COMMUNICATION_ERROR = 'Error communicating with the SSH agent'
-_NO_USABLE_KEYS = 'No usable SSH keys were found'
+_NO_SUITABLE_KEYS = 'No suitable SSH keys were found'
 _EMPTY_SELECTION = 'Empty selection'
+_NOT_AN_INTEGER = 'not an integer'
+_NOT_A_NONNEGATIVE_INTEGER = 'not a non-negative integer'
+_NOT_A_POSITIVE_INTEGER = 'not a positive integer'
 
 
 # Logging
@@ -181,10 +185,15 @@ class CLIofPackageFormatter(logging.Formatter):
         else:  # pragma: no cover
             msg = f'Unsupported logging level: {record.levelname}'
             raise AssertionError(msg)
-        return ''.join(
+        parts = [
+            ''.join(
                 prefix + level_indicator + line
                 for line in preliminary_result.splitlines(True)  # noqa: FBT003
             )
+        ]
+        if record.exc_info:
+            parts.append(self.formatException(record.exc_info) + '\n')
+        return ''.join(parts)
 
 
 class StandardCLILogging:
@@ -393,27 +402,254 @@ class OptionGroupOption(click.Option):
 
     """
 
-    option_group_name: str = ''
+    option_group_name: object = ''
     """"""
-    epilog: str = ''
+    epilog: object = ''
     """"""
 
     def __init__(self, *args: Any, **kwargs: Any) -> None:  # noqa: ANN401
         if self.__class__ == __class__:  # type: ignore[name-defined]
             raise NotImplementedError
+        # Though click 8.1 mostly defers help text processing until the
+        # `BaseCommand.format_*` methods are called, the Option
+        # constructor still preprocesses the help text, and asserts that
+        # the help text is a string.  Work around this by removing the
+        # help text from the constructor arguments and re-adding it,
+        # unprocessed, after constructor finishes.
+        unset = object()
+        help = kwargs.pop('help', unset)  # noqa: A001
         super().__init__(*args, **kwargs)
+        if help is not unset:  # pragma: no branch
+            self.help = help
 
 
 class CommandWithHelpGroups(click.Command):
-    """A [`click.Command`][] with support for help/option groups.
+    """A [`click.Command`][] with support for some help text customizations.
+
+    Supports help/option groups, group epilogs, and help text objects
+    (objects that stringify to help texts).  The latter is primarily
+    used to implement translations.
 
-    Inspired by [a comment on `pallets/click#373`][CLICK_ISSUE], and
-    further modified to support group epilogs.
+    Inspired by [a comment on `pallets/click#373`][CLICK_ISSUE] for
+    help/option group support, and further modified to include group
+    epilogs and help text objects.
 
     [CLICK_ISSUE]: https://github.com/pallets/click/issues/373#issuecomment-515293746
 
     """
 
+    @staticmethod
+    def _text(text: object, /) -> str:
+        if isinstance(text, (list, tuple)):
+            return '\n\n'.join(str(x) for x in text)
+        return str(text)
+
+    def collect_usage_pieces(self, ctx: click.Context) -> list[str]:
+        """Return the pieces for the usage string.
+
+        Based on code from click 8.1.  Subject to the following license
+        (3-clause BSD license):
+
+            Copyright 2024 Pallets
+
+            Redistribution and use in source and binary forms, with or
+            without modification, are permitted provided that the
+            following conditions are met:
+
+             1. Redistributions of source code must retain the above
+                copyright notice, this list of conditions and the
+                following disclaimer.
+
+             2. Redistributions in binary form must reproduce the above
+                copyright notice, this list of conditions and the
+                following disclaimer in the documentation and/or other
+                materials provided with the distribution.
+
+             3. Neither the name of the copyright holder nor the names
+                of its contributors may be used to endorse or promote
+                products derived from this software without specific
+                prior written permission.
+
+            THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
+            CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES,
+            INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+            MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+            DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+            CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+            SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+            NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+            LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+            HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+            CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
+            OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+            SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+        Modifications are marked with respective comments.  They too are
+        released under the same license above.  The original code did
+        not contain any "noqa" or "pragma" comments.
+
+        Args:
+            ctx:
+                The click context.
+
+        """
+        rv = [str(self.options_metavar)] if self.options_metavar else []
+        for param in self.get_params(ctx):
+            rv.extend(str(x) for x in param.get_usage_pieces(ctx))
+        return rv
+
+    def get_short_help_str(
+        self,
+        limit: int = 45,
+    ) -> str:
+        """Return the short help string for a command.
+
+        If only a long help string is given, shorten it.
+
+        Based on code from click 8.1.  Subject to the following license
+        (3-clause BSD license):
+
+            Copyright 2024 Pallets
+
+            Redistribution and use in source and binary forms, with or
+            without modification, are permitted provided that the
+            following conditions are met:
+
+             1. Redistributions of source code must retain the above
+                copyright notice, this list of conditions and the
+                following disclaimer.
+
+             2. Redistributions in binary form must reproduce the above
+                copyright notice, this list of conditions and the
+                following disclaimer in the documentation and/or other
+                materials provided with the distribution.
+
+             3. Neither the name of the copyright holder nor the names
+                of its contributors may be used to endorse or promote
+                products derived from this software without specific
+                prior written permission.
+
+            THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
+            CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES,
+            INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+            MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+            DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+            CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+            SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+            NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+            LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+            HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+            CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
+            OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+            SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+        Modifications are marked with respective comments.  They too are
+        released under the same license above.  The original code did
+        not contain any "noqa" or "pragma" comments.
+
+        Args:
+            limit:
+                The maximum width of the short help string.
+
+        """
+        # Modification against click 8.1: Call `_text()` on `self.help`
+        # to allow help texts to be general objects, not just strings.
+        # Used to implement translatable strings, as objects that
+        # stringify to the translation.
+        if self.short_help:  # pragma: no cover
+            text = inspect.cleandoc(self._text(self.short_help))
+        elif self.help:
+            text = click.utils.make_default_short_help(
+                self._text(self.help), limit
+            )
+        else:  # pragma: no cover
+            text = ''
+        if self.deprecated:  # pragma: no cover
+            # Modification against click 8.1: The translated string is
+            # looked up in the derivepassphrase message domain, not the
+            # gettext default domain.
+            text = str(
+                _msg.TranslatedString(_msg.Label.DEPRECATED_COMMAND_LABEL)
+            ).format(text=text)
+        return text.strip()
+
+    def format_help_text(
+        self,
+        ctx: click.Context,
+        formatter: click.HelpFormatter,
+    ) -> None:
+        """Format the help text prologue, if any.
+
+        Based on code from click 8.1.  Subject to the following license
+        (3-clause BSD license):
+
+            Copyright 2024 Pallets
+
+            Redistribution and use in source and binary forms, with or
+            without modification, are permitted provided that the
+            following conditions are met:
+
+             1. Redistributions of source code must retain the above
+                copyright notice, this list of conditions and the
+                following disclaimer.
+
+             2. Redistributions in binary form must reproduce the above
+                copyright notice, this list of conditions and the
+                following disclaimer in the documentation and/or other
+                materials provided with the distribution.
+
+             3. Neither the name of the copyright holder nor the names
+                of its contributors may be used to endorse or promote
+                products derived from this software without specific
+                prior written permission.
+
+            THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
+            CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES,
+            INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+            MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+            DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+            CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+            SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+            NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+            LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+            HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+            CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
+            OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+            SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+        Modifications are marked with respective comments.  They too are
+        released under the same license above.  The original code did
+        not contain any "noqa" or "pragma" comments.
+
+        Args:
+            ctx:
+                The click context.
+            formatter:
+                The formatter for the `--help` listing.
+
+        """
+        del ctx
+        # Modification against click 8.1: Call `_text()` on `self.help`
+        # to allow help texts to be general objects, not just strings.
+        # Used to implement translatable strings, as objects that
+        # stringify to the translation.
+        text = (
+            inspect.cleandoc(self._text(self.help).partition('\f')[0])
+            if self.help is not None
+            else ''
+        )
+        if self.deprecated:  # pragma: no cover
+            # Modification against click 8.1: The translated string is
+            # looked up in the derivepassphrase message domain, not the
+            # gettext default domain.
+            text = str(
+                _msg.TranslatedString(_msg.Label.DEPRECATED_COMMAND_LABEL)
+            ).format(text=text)
+        if text:  # pragma: no branch
+            formatter.write_paragraph()
+            with formatter.indentation():
+                formatter.write_text(text)
+
     def format_options(
         self,
         ctx: click.Context,
@@ -433,6 +669,48 @@ class CommandWithHelpGroups(click.Command):
         section heading is "Options" (or "Other options" if there are
         other option groups) and the epilog is empty.
 
+        We unconditionally call [`format_commands`][], and rely on it to
+        act as a no-op if we aren't actually a [`click.MultiCommand`][].
+
+        Based on code from click 8.1.  Subject to the following license
+        (3-clause BSD license):
+
+            Copyright 2024 Pallets
+
+            Redistribution and use in source and binary forms, with or
+            without modification, are permitted provided that the
+            following conditions are met:
+
+             1. Redistributions of source code must retain the above
+                copyright notice, this list of conditions and the
+                following disclaimer.
+
+             2. Redistributions in binary form must reproduce the above
+                copyright notice, this list of conditions and the
+                following disclaimer in the documentation and/or other
+                materials provided with the distribution.
+
+             3. Neither the name of the copyright holder nor the names
+                of its contributors may be used to endorse or promote
+                products derived from this software without specific
+                prior written permission.
+
+            THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
+            CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES,
+            INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+            MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+            DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+            CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+            SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+            NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+            LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+            HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+            CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
+            OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+            SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+        Modifications are released under the same license above.
+
         Args:
             ctx:
                 The click context.
@@ -440,6 +718,7 @@ class CommandWithHelpGroups(click.Command):
                 The formatter for the `--help` listing.
 
         """
+        default_group_name = ''
         help_records: dict[str, list[tuple[str, str]]] = {}
         epilogs: dict[str, str] = {}
         params = self.params[:]
@@ -451,15 +730,22 @@ class CommandWithHelpGroups(click.Command):
         for param in params:
             rec = param.get_help_record(ctx)
             if rec is not None:
+                rec = (rec[0], self._text(rec[1]))
                 if isinstance(param, OptionGroupOption):
-                    group_name = param.option_group_name
-                    epilogs.setdefault(group_name, param.epilog)
+                    group_name = self._text(param.option_group_name)
+                    epilogs.setdefault(group_name, self._text(param.epilog))
                 else:
-                    group_name = ''
+                    group_name = default_group_name
                 help_records.setdefault(group_name, []).append(rec)
-        default_group = help_records.pop('')
-        default_group_name = (
-            'Other Options' if len(default_group) > 1 else 'Options'
+        if default_group_name in help_records:  # pragma: no branch
+            default_group = help_records.pop(default_group_name)
+            default_group_label = (
+                _msg.Label.OTHER_OPTIONS_LABEL
+                if len(default_group) > 1
+                else _msg.Label.OPTIONS_LABEL
+            )
+            default_group_name = self._text(
+                _msg.TranslatedString(default_group_label)
             )
             help_records[default_group_name] = default_group
         for group_name, records in help_records.items():
@@ -470,12 +756,158 @@ class CommandWithHelpGroups(click.Command):
                 formatter.write_paragraph()
                 with formatter.indentation():
                     formatter.write_text(epilog)
+        self.format_commands(ctx, formatter)
+
+    def format_commands(
+        self,
+        ctx: click.Context,
+        formatter: click.HelpFormatter,
+    ) -> None:
+        """Format the subcommands, if any.
+
+        If called on a command object that isn't derived from
+        [`click.MultiCommand`][], then do nothing.
+
+        Based on code from click 8.1.  Subject to the following license
+        (3-clause BSD license):
+
+            Copyright 2024 Pallets
+
+            Redistribution and use in source and binary forms, with or
+            without modification, are permitted provided that the
+            following conditions are met:
+
+             1. Redistributions of source code must retain the above
+                copyright notice, this list of conditions and the
+                following disclaimer.
+
+             2. Redistributions in binary form must reproduce the above
+                copyright notice, this list of conditions and the
+                following disclaimer in the documentation and/or other
+                materials provided with the distribution.
+
+             3. Neither the name of the copyright holder nor the names
+                of its contributors may be used to endorse or promote
+                products derived from this software without specific
+                prior written permission.
+
+            THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
+            CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES,
+            INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+            MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+            DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+            CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+            SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+            NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+            LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+            HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+            CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
+            OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+            SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+        Modifications are marked with respective comments.  They too are
+        released under the same license above.  The original code did
+        not contain any "noqa" or "pragma" comments.
+
+        Args:
+            ctx:
+                The click context.
+            formatter:
+                The formatter for the `--help` listing.
+
+        """
+        if not isinstance(self, click.MultiCommand):
+            return
+        commands: list[tuple[str, click.Command]] = []
+        for subcommand in self.list_commands(ctx):
+            cmd = self.get_command(ctx, subcommand)
+            if cmd is None or cmd.hidden:  # pragma: no cover
+                continue
+            commands.append((subcommand, cmd))
+        if commands:  # pragma: no branch
+            longest_command = max((cmd[0] for cmd in commands), key=len)
+            limit = formatter.width - 6 - len(longest_command)
+            rows: list[tuple[str, str]] = []
+            for subcommand, cmd in commands:
+                help_str = self._text(cmd.get_short_help_str(limit) or '')
+                rows.append((subcommand, help_str))
+            if rows:  # pragma: no branch
+                commands_label = self._text(
+                    _msg.TranslatedString(_msg.Label.COMMANDS_LABEL)
+                )
+                with formatter.section(commands_label):
+                    formatter.write_dl(rows)
+
+    def format_epilog(
+        self,
+        ctx: click.Context,
+        formatter: click.HelpFormatter,
+    ) -> None:
+        """Format the epilog, if any.
+
+        Based on code from click 8.1.  Subject to the following license
+        (3-clause BSD license):
+
+            Copyright 2024 Pallets
+
+            Redistribution and use in source and binary forms, with or
+            without modification, are permitted provided that the
+            following conditions are met:
+
+             1. Redistributions of source code must retain the above
+                copyright notice, this list of conditions and the
+                following disclaimer.
+
+             2. Redistributions in binary form must reproduce the above
+                copyright notice, this list of conditions and the
+                following disclaimer in the documentation and/or other
+                materials provided with the distribution.
+
+             3. Neither the name of the copyright holder nor the names
+                of its contributors may be used to endorse or promote
+                products derived from this software without specific
+                prior written permission.
+
+            THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
+            CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES,
+            INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+            MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+            DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+            CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+            SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+            NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+            LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+            HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+            CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
+            OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+            SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+        Modifications are marked with respective comments.  They too are
+        released under the same license above.
+
+        Args:
+            ctx:
+                The click context.
+            formatter:
+                The formatter for the `--help` listing.
+
+        """
+        del ctx
+        if self.epilog:  # pragma: no branch
+            # Modification against click 8.1: Call `str()` on
+            # `self.epilog` to allow help texts to be general objects,
+            # not just strings.  Used to implement translatable strings,
+            # as objects that stringify to the translation.
+            epilog = inspect.cleandoc(self._text(self.epilog))
+            formatter.write_paragraph()
+            with formatter.indentation():
+                formatter.write_text(epilog)
 
 
 class LoggingOption(OptionGroupOption):
     """Logging options for the CLI."""
 
-    option_group_name = 'Logging'
+    option_group_name = _msg.TranslatedString(_msg.Label.LOGGING_LABEL)
     epilog = ''
 
 
@@ -486,7 +918,7 @@ debug_option = click.option(
     flag_value=logging.DEBUG,
     expose_value=False,
     callback=adjust_logging_level,
-    help='also emit debug information (implies --verbose)',
+    help=_msg.TranslatedString(_msg.Label.DEBUG_OPTION_HELP_TEXT),
     cls=LoggingOption,
 )
 verbose_option = click.option(
@@ -497,7 +929,7 @@ verbose_option = click.option(
     flag_value=logging.INFO,
     expose_value=False,
     callback=adjust_logging_level,
-    help='emit extra/progress information to standard error',
+    help=_msg.TranslatedString(_msg.Label.VERBOSE_OPTION_HELP_TEXT),
     cls=LoggingOption,
 )
 quiet_option = click.option(
@@ -508,7 +940,7 @@ quiet_option = click.option(
     flag_value=logging.ERROR,
     expose_value=False,
     callback=adjust_logging_level,
-    help='suppress even warnings, emit only errors',
+    help=_msg.TranslatedString(_msg.Label.QUIET_OPTION_HELP_TEXT),
     cls=LoggingOption,
 )
 
@@ -534,7 +966,7 @@ def standard_logging_options(f: Callable[P, R]) -> Callable[P, R]:
 # =========
 
 
-class _DefaultToVaultGroup(click.Group):
+class _DefaultToVaultGroup(CommandWithHelpGroups, click.Group):
     """A helper class to implement the default-to-"vault"-subcommand behavior.
 
     Modifies internal [`click.MultiCommand`][] methods, and thus is both
@@ -548,16 +980,53 @@ class _DefaultToVaultGroup(click.Group):
         """Resolve a command, but default to "vault" instead of erroring out.
 
         Based on code from click 8.1, which appears to be essentially
-        untouched since at least click 3.2.
+        untouched since at least click 3.2.  Subject to the following
+        license (3-clause BSD license):
+
+            Copyright 2024 Pallets
+
+            Redistribution and use in source and binary forms, with or
+            without modification, are permitted provided that the following
+            conditions are met:
+
+             1. Redistributions of source code must retain the above
+                copyright notice, this list of conditions and the following
+                disclaimer.
+
+             2. Redistributions in binary form must reproduce the above
+                copyright notice, this list of conditions and the following
+                disclaimer in the documentation and/or other materials
+                provided with the distribution.
+
+             3. Neither the name of the copyright holder nor the names of
+                its contributors may be used to endorse or promote products
+                derived from this software without specific prior written
+                permission.
+
+            THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
+            CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES,
+            INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+            MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+            DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+            CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+            SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+            LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
+            USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
+            AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+            LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
+            IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+            THE POSSIBILITY OF SUCH DAMAGE.
+
+        Modifications to this routine are marked with "modifications for
+        derivepassphrase".  Furthermore, all "pragma" and "noqa" comments
+        are also modifications for derivepassphrase.
 
         """
         cmd_name = click.utils.make_str(args[0])
 
-        # ORIGINAL COMMENT
         # Get the command
         cmd = self.get_command(ctx, cmd_name)
 
-        # ORIGINAL COMMENT
         # If we can't find the command but there is a normalization
         # function available, we try with that one.
         if (  # pragma: no cover
@@ -566,7 +1035,6 @@ class _DefaultToVaultGroup(click.Group):
             cmd_name = ctx.token_normalize_func(cmd_name)
             cmd = self.get_command(ctx, cmd_name)
 
-        # ORIGINAL COMMENT
         # If we don't find the command we want to show an error message
         # to the user that it was not provided.  However, there is
         # something else we should do: if the first argument looks like
@@ -576,19 +1044,24 @@ class _DefaultToVaultGroup(click.Group):
         if cmd is None and not ctx.resilient_parsing:
             if click.parser.split_opt(cmd_name)[0]:
                 self.parse_args(ctx, ctx.args)
+            ####
+            # BEGIN modifications for derivepassphrase
+            #
             # Instead of calling ctx.fail here, default to "vault", and
             # issue a deprecation warning.
-            logger = logging.getLogger(PROG_NAME)
             deprecation = logging.getLogger(f'{PROG_NAME}.deprecation')
             deprecation.warning(
-                'A subcommand will be required in v1.0. '
-                'See --help for available subcommands.'
+                _msg.TranslatedString(
+                    _msg.WarnMsgTemplate.V10_SUBCOMMAND_REQUIRED
+                )
             )
-            logger.warning('Defaulting to subcommand "vault".')
             cmd_name = 'vault'
             cmd = self.get_command(ctx, cmd_name)
             assert cmd is not None, 'Mandatory subcommand "vault" missing!'
             args = [cmd_name, *args]
+            #
+            # END modifications for derivepassphrase
+            ####
         return cmd_name if cmd else None, cmd, args[1:]  # noqa: DOC201
 
 
@@ -628,14 +1101,14 @@ class _TopLevelCLIEntryPoint(_DefaultToVaultGroup):
         'ignore_unknown_options': True,
         'allow_interspersed_args': False,
     },
-    epilog=r"""
-        Configuration is stored in a directory according to the
-        DERIVEPASSPHRASE_PATH variable, which defaults to
-        `~/.derivepassphrase` on UNIX-like systems and
-        `C:\Users\<user>\AppData\Roaming\Derivepassphrase` on Windows.
-    """,
+    epilog=_msg.TranslatedString(_msg.Label.DERIVEPASSPHRASE_EPILOG_01),
     invoke_without_command=True,
     cls=_TopLevelCLIEntryPoint,
+    help=(
+        _msg.TranslatedString(_msg.Label.DERIVEPASSPHRASE_01),
+        _msg.TranslatedString(_msg.Label.DERIVEPASSPHRASE_02),
+        _msg.TranslatedString(_msg.Label.DERIVEPASSPHRASE_03),
+    ),
 )
 @click.version_option(version=dpp.__version__, prog_name=PROG_NAME)
 @standard_logging_options
@@ -643,41 +1116,20 @@ class _TopLevelCLIEntryPoint(_DefaultToVaultGroup):
 def derivepassphrase(ctx: click.Context, /) -> None:
     """Derive a strong passphrase, deterministically, from a master secret.
 
-    Using a master secret, derive a passphrase for a named service,
-    subject to constraints e.g. on passphrase length, allowed
-    characters, etc.  The exact derivation depends on the selected
-    derivation scheme.  For each scheme, it is computationally
-    infeasible to discern the master secret from the derived passphrase.
-    The derivations are also deterministic, given the same inputs, thus
-    the resulting passphrases need not be stored explicitly.  The
-    service name and constraints themselves also generally need not be
-    kept secret, depending on the scheme.
-
-    The currently implemented subcommands are "vault" (for the scheme
-    used by vault) and "export" (for exporting foreign configuration
-    data).  See the respective `--help` output for instructions.  If no
-    subcommand is given, we default to "vault".
-
-    Deprecation notice: Defaulting to "vault" is deprecated.  Starting
-    in v1.0, the subcommand must be specified explicitly.\f
-
     This is a [`click`][CLICK]-powered command-line interface function,
-    and not intended for programmatic use.  Call with arguments
-    `['--help']` to see full documentation of the interface.  (See also
+    and not intended for programmatic use.  See the derivepassphrase(1)
+    manpage for full documentation of the interface.  (See also
     [`click.testing.CliRunner`][] for controlled, programmatic
     invocation.)
 
     [CLICK]: https://pypi.org/package/click/
 
-    """  # noqa: D301
-    logger = logging.getLogger(PROG_NAME)
+    """
     deprecation = logging.getLogger(f'{PROG_NAME}.deprecation')
     if ctx.invoked_subcommand is None:
         deprecation.warning(
-            'A subcommand will be required in v1.0. '
-            'See --help for available subcommands.'
+            _msg.TranslatedString(_msg.WarnMsgTemplate.V10_SUBCOMMAND_REQUIRED)
         )
-        logger.warning('Defaulting to subcommand "vault".')
         # See definition of click.Group.invoke, non-chained case.
         with ctx:
             sub_ctx = derivepassphrase_vault.make_context(
@@ -701,6 +1153,11 @@ def derivepassphrase(ctx: click.Context, /) -> None:
     },
     invoke_without_command=True,
     cls=_DefaultToVaultGroup,
+    help=(
+        _msg.TranslatedString(_msg.Label.DERIVEPASSPHRASE_EXPORT_01),
+        _msg.TranslatedString(_msg.Label.DERIVEPASSPHRASE_EXPORT_02),
+        _msg.TranslatedString(_msg.Label.DERIVEPASSPHRASE_EXPORT_03),
+    ),
 )
 @click.version_option(version=dpp.__version__, prog_name=PROG_NAME)
 @standard_logging_options
@@ -708,33 +1165,20 @@ def derivepassphrase(ctx: click.Context, /) -> None:
 def derivepassphrase_export(ctx: click.Context, /) -> None:
     """Export a foreign configuration to standard output.
 
-    Read a foreign system configuration, extract all information from
-    it, and export the resulting configuration to standard output.
-
-    The only available subcommand is "vault", which implements the
-    vault-native configuration scheme.  If no subcommand is given, we
-    default to "vault".
-
-    Deprecation notice: Defaulting to "vault" is deprecated.  Starting
-    in v1.0, the subcommand must be specified explicitly.\f
-
     This is a [`click`][CLICK]-powered command-line interface function,
-    and not intended for programmatic use.  Call with arguments
-    `['--help']` to see full documentation of the interface.  (See also
-    [`click.testing.CliRunner`][] for controlled, programmatic
-    invocation.)
+    and not intended for programmatic use.  See the
+    derivepassphrase-export(1) manpage for full documentation of the
+    interface.  (See also [`click.testing.CliRunner`][] for controlled,
+    programmatic invocation.)
 
     [CLICK]: https://pypi.org/package/click/
 
-    """  # noqa: D301
-    logger = logging.getLogger(PROG_NAME)
+    """
     deprecation = logging.getLogger(f'{PROG_NAME}.deprecation')
     if ctx.invoked_subcommand is None:
         deprecation.warning(
-            'A subcommand will be required in v1.0. '
-            'See --help for available subcommands.'
+            _msg.TranslatedString(_msg.WarnMsgTemplate.V10_SUBCOMMAND_REQUIRED)
         )
-        logger.warning('Defaulting to subcommand "vault".')
         # See definition of click.Group.invoke, non-chained case.
         with ctx:
             sub_ctx = derivepassphrase_export_vault.make_context(
@@ -787,32 +1231,68 @@ def _load_data(
         assert_never(fmt)
 
 
+class StandardOption(OptionGroupOption):
+    pass
+
+
 @derivepassphrase_export.command(
     'vault',
     context_settings={'help_option_names': ['-h', '--help']},
+    cls=CommandWithHelpGroups,
+    help=(
+        _msg.TranslatedString(_msg.Label.DERIVEPASSPHRASE_EXPORT_VAULT_01),
+        _msg.TranslatedString(
+            _msg.Label.DERIVEPASSPHRASE_EXPORT_VAULT_02,
+            path_metavar=_msg.TranslatedString(
+                _msg.Label.EXPORT_VAULT_METAVAR_PATH,
+            ),
+        ),
+        _msg.TranslatedString(
+            _msg.Label.DERIVEPASSPHRASE_EXPORT_VAULT_03,
+            path_metavar=_msg.TranslatedString(
+                _msg.Label.EXPORT_VAULT_METAVAR_PATH,
+            ),
+        ),
+    ),
 )
 @standard_logging_options
 @click.option(
     '-f',
     '--format',
     'formats',
-    metavar='FMT',
+    metavar=_msg.TranslatedString(_msg.Label.EXPORT_VAULT_FORMAT_METAVAR_FMT),
     multiple=True,
     default=('v0.3', 'v0.2', 'storeroom'),
     type=click.Choice(['v0.2', 'v0.3', 'storeroom']),
-    help='try the following storage formats, in order (default: v0.3, v0.2)',
+    help=_msg.TranslatedString(
+        _msg.Label.EXPORT_VAULT_FORMAT_HELP_TEXT,
+        defaults_hint=_msg.TranslatedString(
+            _msg.Label.EXPORT_VAULT_FORMAT_DEFAULTS_HELP_TEXT,
+        ),
+        metavar=_msg.TranslatedString(
+            _msg.Label.EXPORT_VAULT_FORMAT_METAVAR_FMT,
+        ),
+    ),
+    cls=StandardOption,
 )
 @click.option(
     '-k',
     '--key',
-    metavar='K',
-    help=(
-        'use K as the storage master key '
-        '(default: check the `VAULT_KEY`, `LOGNAME`, `USER` or '
-        '`USERNAME` environment variables)'
+    metavar=_msg.TranslatedString(_msg.Label.EXPORT_VAULT_KEY_METAVAR_K),
+    help=_msg.TranslatedString(
+        _msg.Label.EXPORT_VAULT_KEY_HELP_TEXT,
+        metavar=_msg.TranslatedString(_msg.Label.EXPORT_VAULT_KEY_METAVAR_K),
+        defaults_hint=_msg.TranslatedString(
+            _msg.Label.EXPORT_VAULT_KEY_DEFAULTS_HELP_TEXT,
         ),
+    ),
+    cls=StandardOption,
+)
+@click.argument(
+    'path',
+    metavar=_msg.TranslatedString(_msg.Label.EXPORT_VAULT_METAVAR_PATH),
+    required=True,
 )
-@click.argument('path', metavar='PATH', required=True)
 @click.pass_context
 def derivepassphrase_export_vault(
     ctx: click.Context,
@@ -824,16 +1304,13 @@ def derivepassphrase_export_vault(
 ) -> None:
     """Export a vault-native configuration to standard output.
 
-    Read the vault-native configuration at PATH, extract all information
-    from it, and export the resulting configuration to standard output.
-    Depending on the configuration format, PATH may either be a file or
-    a directory.  Supports the vault "v0.2", "v0.3" and "storeroom"
-    formats.
+    This is a [`click`][CLICK]-powered command-line interface function,
+    and not intended for programmatic use.  See the
+    derivepassphrase-export-vault(1) manpage for full documentation of
+    the interface.  (See also [`click.testing.CliRunner`][] for
+    controlled, programmatic invocation.)
 
-    If PATH is explicitly given as `VAULT_PATH`, then use the
-    `VAULT_PATH` environment variable to determine the correct path.
-    (Use `./VAULT_PATH` or similar to indicate a file/directory actually
-    named `VAULT_PATH`.)
+    [CLICK]: https://pypi.org/package/click/
 
     """
     logger = logging.getLogger(PROG_NAME)
@@ -1093,7 +1570,7 @@ def _get_suitable_ssh_keys(
             if vault.Vault.is_suitable_ssh_key(key, client=client):
                 yield pair
     if not suitable_keys:  # pragma: no cover
-        raise LookupError(_NO_USABLE_KEYS)
+        raise LookupError(_NO_SUITABLE_KEYS)
 
 
 def _prompt_for_selection(
@@ -1317,9 +1794,11 @@ def _check_for_misleading_passphrase(
         if not unicodedata.is_normalized(form, phrase):
             logger.warning(
                 (
-                    'the %s passphrase is not %s-normalized.  '
-                    'Make sure to double-check this is really the '
-                    'passphrase you want.'
+                    'The %s passphrase is not %s-normalized.  Its '
+                    'serialization as a byte string may not be what you '
+                    'expect it to be, even if it *displays* correctly.  '
+                    'Please make sure to double-check any derived '
+                    'passphrases for unexpected results.'
                 ),
                 formatted_key,
                 form,
@@ -1350,19 +1829,35 @@ def _key_to_phrase(
                         k == key for k, _ in keylist
                     ):
                         error_callback(
-                            'The requested SSH key is not loaded '
-                            'into the agent.'
+                            _msg.TranslatedString(
+                                _msg.ErrMsgTemplate.SSH_KEY_NOT_LOADED
+                            )
+                        )
+                error_callback(
+                    _msg.TranslatedString(
+                        _msg.ErrMsgTemplate.AGENT_REFUSED_SIGNATURE
+                    ),
+                    exc_info=exc,
                 )
-                error_callback(exc)
     except KeyError:
-        error_callback('Cannot find running SSH agent; check SSH_AUTH_SOCK')
-    except NotImplementedError:
         error_callback(
-            'Cannot connect to SSH agent because '
-            'this Python version does not support UNIX domain sockets'
+            _msg.TranslatedString(_msg.ErrMsgTemplate.NO_SSH_AGENT_FOUND)
         )
+    except NotImplementedError:
+        error_callback(_msg.TranslatedString(_msg.ErrMsgTemplate.NO_AF_UNIX))
     except OSError as exc:
-        error_callback('Cannot connect to SSH agent: %s', exc.strerror)
+        error_callback(
+            _msg.TranslatedString(
+                _msg.ErrMsgTemplate.CANNOT_CONNECT_TO_AGENT,
+                error=exc.strerror,
+                filename=exc.filename,
+            ).maybe_without_filename()
+        )
+    except RuntimeError as exc:
+        error_callback(
+            _msg.TranslatedString(_msg.ErrMsgTemplate.CANNOT_UNDERSTAND_AGENT),
+            exc_info=exc,
+        )
 
 
 def _print_config_as_sh_script(
@@ -1441,36 +1936,44 @@ def _print_config_as_sh_script(
 class PassphraseGenerationOption(OptionGroupOption):
     """Passphrase generation options for the CLI."""
 
-    option_group_name = 'Passphrase generation'
-    epilog = """
-        Use NUMBER=0, e.g. "--symbol 0", to exclude a character type
-        from the output.
-    """
+    option_group_name = _msg.TranslatedString(
+        _msg.Label.PASSPHRASE_GENERATION_LABEL
+    )
+    epilog = _msg.TranslatedString(
+        _msg.Label.PASSPHRASE_GENERATION_EPILOG,
+        metavar=_msg.TranslatedString(
+            _msg.Label.PASSPHRASE_GENERATION_METAVAR_NUMBER
+        ),
+    )
 
 
 class ConfigurationOption(OptionGroupOption):
     """Configuration options for the CLI."""
 
-    option_group_name = 'Configuration'
-    epilog = """
-        Use $VISUAL or $EDITOR to configure the spawned editor.
-    """
+    option_group_name = _msg.TranslatedString(_msg.Label.CONFIGURATION_LABEL)
+    epilog = _msg.TranslatedString(_msg.Label.CONFIGURATION_EPILOG)
 
 
 class StorageManagementOption(OptionGroupOption):
     """Storage management options for the CLI."""
 
-    option_group_name = 'Storage management'
-    epilog = """
-        Using "-" as PATH for standard input/standard output is
-        supported.
-    """
+    option_group_name = _msg.TranslatedString(
+        _msg.Label.STORAGE_MANAGEMENT_LABEL
+    )
+    epilog = _msg.TranslatedString(
+        _msg.Label.STORAGE_MANAGEMENT_EPILOG,
+        metavar=_msg.TranslatedString(
+            _msg.Label.STORAGE_MANAGEMENT_METAVAR_PATH
+        ),
+    )
 
 
 class CompatibilityOption(OptionGroupOption):
     """Compatibility and incompatibility options for the CLI."""
 
-    option_group_name = 'Compatibility and extension options'
+    option_group_name = _msg.TranslatedString(
+        _msg.Label.COMPATIBILITY_OPTION_LABEL
+    )
 
 
 def _validate_occurrence_constraint(
@@ -1502,11 +2005,9 @@ def _validate_occurrence_constraint(
         try:
             int_value = int(value, 10)
         except ValueError as exc:
-            msg = 'not an integer'
-            raise click.BadParameter(msg) from exc
+            raise click.BadParameter(_NOT_AN_INTEGER) from exc
     if int_value < 0:
-        msg = 'not a non-negative integer'
-        raise click.BadParameter(msg)
+        raise click.BadParameter(_NOT_A_NONNEGATIVE_INTEGER)
     return int_value
 
 
@@ -1539,11 +2040,9 @@ def _validate_length(
         try:
             int_value = int(value, 10)
         except ValueError as exc:
-            msg = 'not an integer'
-            raise click.BadParameter(msg) from exc
+            raise click.BadParameter(_NOT_AN_INTEGER) from exc
     if int_value < 1:
-        msg = 'not a positive integer'
-        raise click.BadParameter(msg)
+        raise click.BadParameter(_NOT_A_POSITIVE_INTEGER)
     return int_value
 
 
@@ -1565,23 +2064,28 @@ DEFAULT_NOTES_MARKER = '# - - - - - >8 - - - - -'
     'vault',
     context_settings={'help_option_names': ['-h', '--help']},
     cls=CommandWithHelpGroups,
-    epilog=r"""
-        WARNING: There is NO WAY to retrieve the generated passphrases
-        if the master passphrase, the SSH key, or the exact passphrase
-        settings are lost, short of trying out all possible
-        combinations.  You are STRONGLY advised to keep independent
-        backups of the settings and the SSH key, if any.
-
-        The configuration is NOT encrypted, and you are STRONGLY
-        discouraged from using a stored passphrase.
-    """,
+    help=(
+        _msg.TranslatedString(_msg.Label.DERIVEPASSPHRASE_VAULT_01),
+        _msg.TranslatedString(
+            _msg.Label.DERIVEPASSPHRASE_VAULT_02,
+            service_metavar=_msg.TranslatedString(
+                _msg.Label.VAULT_METAVAR_SERVICE
+            ),
+        ),
+    ),
+    epilog=(
+        _msg.TranslatedString(_msg.Label.DERIVEPASSPHRASE_VAULT_EPILOG_01),
+        _msg.TranslatedString(_msg.Label.DERIVEPASSPHRASE_VAULT_EPILOG_02),
+    ),
 )
 @click.option(
     '-p',
     '--phrase',
     'use_phrase',
     is_flag=True,
-    help='prompts you for your passphrase',
+    help=_msg.TranslatedString(
+        _msg.Label.DERIVEPASSPHRASE_VAULT_PHRASE_HELP_TEXT
+    ),
     cls=PassphraseGenerationOption,
 )
 @click.option(
@@ -1589,65 +2093,123 @@ DEFAULT_NOTES_MARKER = '# - - - - - >8 - - - - -'
     '--key',
     'use_key',
     is_flag=True,
-    help='uses your SSH private key to generate passwords',
+    help=_msg.TranslatedString(
+        _msg.Label.DERIVEPASSPHRASE_VAULT_KEY_HELP_TEXT
+    ),
     cls=PassphraseGenerationOption,
 )
 @click.option(
     '-l',
     '--length',
-    metavar='NUMBER',
+    metavar=_msg.TranslatedString(
+        _msg.Label.PASSPHRASE_GENERATION_METAVAR_NUMBER
+    ),
     callback=_validate_length,
-    help='emits password of length NUMBER',
+    help=_msg.TranslatedString(
+        _msg.Label.DERIVEPASSPHRASE_VAULT_LENGTH_HELP_TEXT,
+        metavar=_msg.TranslatedString(
+            _msg.Label.PASSPHRASE_GENERATION_METAVAR_NUMBER
+        ),
+    ),
     cls=PassphraseGenerationOption,
 )
 @click.option(
     '-r',
     '--repeat',
-    metavar='NUMBER',
+    metavar=_msg.TranslatedString(
+        _msg.Label.PASSPHRASE_GENERATION_METAVAR_NUMBER
+    ),
     callback=_validate_occurrence_constraint,
-    help='allows maximum of NUMBER repeated adjacent chars',
+    help=_msg.TranslatedString(
+        _msg.Label.DERIVEPASSPHRASE_VAULT_REPEAT_HELP_TEXT,
+        metavar=_msg.TranslatedString(
+            _msg.Label.PASSPHRASE_GENERATION_METAVAR_NUMBER
+        ),
+    ),
     cls=PassphraseGenerationOption,
 )
 @click.option(
     '--lower',
-    metavar='NUMBER',
+    metavar=_msg.TranslatedString(
+        _msg.Label.PASSPHRASE_GENERATION_METAVAR_NUMBER
+    ),
     callback=_validate_occurrence_constraint,
-    help='includes at least NUMBER lowercase letters',
+    help=_msg.TranslatedString(
+        _msg.Label.DERIVEPASSPHRASE_VAULT_LOWER_HELP_TEXT,
+        metavar=_msg.TranslatedString(
+            _msg.Label.PASSPHRASE_GENERATION_METAVAR_NUMBER
+        ),
+    ),
     cls=PassphraseGenerationOption,
 )
 @click.option(
     '--upper',
-    metavar='NUMBER',
+    metavar=_msg.TranslatedString(
+        _msg.Label.PASSPHRASE_GENERATION_METAVAR_NUMBER
+    ),
     callback=_validate_occurrence_constraint,
-    help='includes at least NUMBER uppercase letters',
+    help=_msg.TranslatedString(
+        _msg.Label.DERIVEPASSPHRASE_VAULT_UPPER_HELP_TEXT,
+        metavar=_msg.TranslatedString(
+            _msg.Label.PASSPHRASE_GENERATION_METAVAR_NUMBER
+        ),
+    ),
     cls=PassphraseGenerationOption,
 )
 @click.option(
     '--number',
-    metavar='NUMBER',
+    metavar=_msg.TranslatedString(
+        _msg.Label.PASSPHRASE_GENERATION_METAVAR_NUMBER
+    ),
     callback=_validate_occurrence_constraint,
-    help='includes at least NUMBER digits',
+    help=_msg.TranslatedString(
+        _msg.Label.DERIVEPASSPHRASE_VAULT_NUMBER_HELP_TEXT,
+        metavar=_msg.TranslatedString(
+            _msg.Label.PASSPHRASE_GENERATION_METAVAR_NUMBER
+        ),
+    ),
     cls=PassphraseGenerationOption,
 )
 @click.option(
     '--space',
-    metavar='NUMBER',
+    metavar=_msg.TranslatedString(
+        _msg.Label.PASSPHRASE_GENERATION_METAVAR_NUMBER
+    ),
     callback=_validate_occurrence_constraint,
-    help='includes at least NUMBER spaces',
+    help=_msg.TranslatedString(
+        _msg.Label.DERIVEPASSPHRASE_VAULT_SPACE_HELP_TEXT,
+        metavar=_msg.TranslatedString(
+            _msg.Label.PASSPHRASE_GENERATION_METAVAR_NUMBER
+        ),
+    ),
     cls=PassphraseGenerationOption,
 )
 @click.option(
     '--dash',
-    metavar='NUMBER',
+    metavar=_msg.TranslatedString(
+        _msg.Label.PASSPHRASE_GENERATION_METAVAR_NUMBER
+    ),
     callback=_validate_occurrence_constraint,
-    help='includes at least NUMBER "-" or "_"',
+    help=_msg.TranslatedString(
+        _msg.Label.DERIVEPASSPHRASE_VAULT_DASH_HELP_TEXT,
+        metavar=_msg.TranslatedString(
+            _msg.Label.PASSPHRASE_GENERATION_METAVAR_NUMBER
+        ),
+    ),
     cls=PassphraseGenerationOption,
 )
 @click.option(
     '--symbol',
-    metavar='NUMBER',
+    metavar=_msg.TranslatedString(
+        _msg.Label.PASSPHRASE_GENERATION_METAVAR_NUMBER
+    ),
     callback=_validate_occurrence_constraint,
-    help='includes at least NUMBER symbol chars',
+    help=_msg.TranslatedString(
+        _msg.Label.DERIVEPASSPHRASE_VAULT_SYMBOL_HELP_TEXT,
+        metavar=_msg.TranslatedString(
+            _msg.Label.PASSPHRASE_GENERATION_METAVAR_NUMBER
+        ),
+    ),
     cls=PassphraseGenerationOption,
 )
 @click.option(
@@ -1655,7 +2217,12 @@ DEFAULT_NOTES_MARKER = '# - - - - - >8 - - - - -'
     '--notes',
     'edit_notes',
     is_flag=True,
-    help='spawn an editor to edit notes for SERVICE',
+    help=_msg.TranslatedString(
+        _msg.Label.DERIVEPASSPHRASE_VAULT_NOTES_HELP_TEXT,
+        service_metavar=_msg.TranslatedString(
+            _msg.Label.VAULT_METAVAR_SERVICE
+        ),
+    ),
     cls=ConfigurationOption,
 )
 @click.option(
@@ -1663,7 +2230,12 @@ DEFAULT_NOTES_MARKER = '# - - - - - >8 - - - - -'
     '--config',
     'store_config_only',
     is_flag=True,
-    help='saves the given settings for SERVICE or global',
+    help=_msg.TranslatedString(
+        _msg.Label.DERIVEPASSPHRASE_VAULT_CONFIG_HELP_TEXT,
+        service_metavar=_msg.TranslatedString(
+            _msg.Label.VAULT_METAVAR_SERVICE
+        ),
+    ),
     cls=ConfigurationOption,
 )
 @click.option(
@@ -1671,13 +2243,20 @@ DEFAULT_NOTES_MARKER = '# - - - - - >8 - - - - -'
     '--delete',
     'delete_service_settings',
     is_flag=True,
-    help='deletes settings for SERVICE',
+    help=_msg.TranslatedString(
+        _msg.Label.DERIVEPASSPHRASE_VAULT_DELETE_HELP_TEXT,
+        service_metavar=_msg.TranslatedString(
+            _msg.Label.VAULT_METAVAR_SERVICE
+        ),
+    ),
     cls=ConfigurationOption,
 )
 @click.option(
     '--delete-globals',
     is_flag=True,
-    help='deletes the global shared settings',
+    help=_msg.TranslatedString(
+        _msg.Label.DERIVEPASSPHRASE_VAULT_DELETE_GLOBALS_HELP_TEXT,
+    ),
     cls=ConfigurationOption,
 )
 @click.option(
@@ -1685,30 +2264,48 @@ DEFAULT_NOTES_MARKER = '# - - - - - >8 - - - - -'
     '--clear',
     'clear_all_settings',
     is_flag=True,
-    help='deletes all settings',
+    help=_msg.TranslatedString(
+        _msg.Label.DERIVEPASSPHRASE_VAULT_DELETE_ALL_HELP_TEXT,
+    ),
     cls=ConfigurationOption,
 )
 @click.option(
     '-e',
     '--export',
     'export_settings',
-    metavar='PATH',
-    help='export all saved settings into file PATH',
+    metavar=_msg.TranslatedString(
+        _msg.Label.PASSPHRASE_GENERATION_METAVAR_NUMBER
+    ),
+    help=_msg.TranslatedString(
+        _msg.Label.DERIVEPASSPHRASE_VAULT_EXPORT_HELP_TEXT,
+        metavar=_msg.TranslatedString(
+            _msg.Label.PASSPHRASE_GENERATION_METAVAR_NUMBER
+        ),
+    ),
     cls=StorageManagementOption,
 )
 @click.option(
     '-i',
     '--import',
     'import_settings',
-    metavar='PATH',
-    help='import saved settings from file PATH',
+    metavar=_msg.TranslatedString(
+        _msg.Label.PASSPHRASE_GENERATION_METAVAR_NUMBER
+    ),
+    help=_msg.TranslatedString(
+        _msg.Label.DERIVEPASSPHRASE_VAULT_IMPORT_HELP_TEXT,
+        metavar=_msg.TranslatedString(
+            _msg.Label.PASSPHRASE_GENERATION_METAVAR_NUMBER
+        ),
+    ),
     cls=StorageManagementOption,
 )
 @click.option(
     '--overwrite-existing/--merge-existing',
     'overwrite_config',
     default=False,
-    help='overwrite or merge (default) the existing configuration',
+    help=_msg.TranslatedString(
+        _msg.Label.DERIVEPASSPHRASE_VAULT_OVERWRITE_HELP_TEXT
+    ),
     cls=CompatibilityOption,
 )
 @click.option(
@@ -1727,9 +2324,8 @@ DEFAULT_NOTES_MARKER = '# - - - - - >8 - - - - -'
         'dash',
         'symbol',
     ]),
-    help=(
-        'with --config, also unsets the given setting; '
-        'may be specified multiple times'
+    help=_msg.TranslatedString(
+        _msg.Label.DERIVEPASSPHRASE_VAULT_UNSET_HELP_TEXT
     ),
     cls=CompatibilityOption,
 )
@@ -1737,12 +2333,19 @@ DEFAULT_NOTES_MARKER = '# - - - - - >8 - - - - -'
     '--export-as',
     type=click.Choice(['json', 'sh']),
     default='json',
-    help='when exporting, export as JSON (default) or POSIX sh',
+    help=_msg.TranslatedString(
+        _msg.Label.DERIVEPASSPHRASE_VAULT_EXPORT_AS_HELP_TEXT
+    ),
     cls=CompatibilityOption,
 )
 @click.version_option(version=dpp.__version__, prog_name=PROG_NAME)
 @standard_logging_options
-@click.argument('service', required=False)
+@click.argument(
+    'service',
+    metavar=_msg.TranslatedString(_msg.Label.VAULT_METAVAR_SERVICE),
+    required=False,
+    default=None,
+)
 @click.pass_context
 def derivepassphrase_vault(  # noqa: C901,PLR0912,PLR0913,PLR0914,PLR0915
     ctx: click.Context,
@@ -1772,24 +2375,11 @@ def derivepassphrase_vault(  # noqa: C901,PLR0912,PLR0913,PLR0914,PLR0915
 ) -> None:
     """Derive a passphrase using the vault(1) derivation scheme.
 
-    Using a master passphrase or a master SSH key, derive a passphrase
-    for SERVICE, subject to length, character and character repetition
-    constraints.  The derivation is cryptographically strong, meaning
-    that even if a single passphrase is compromised, guessing the master
-    passphrase or a different service's passphrase is computationally
-    infeasible.  The derivation is also deterministic, given the same
-    inputs, thus the resulting passphrase need not be stored explicitly.
-    The service name and constraints themselves also need not be kept
-    secret; the latter are usually stored in a world-readable file.
-
-    If operating on global settings, or importing/exporting settings,
-    then SERVICE must be omitted.  Otherwise it is required.\f
-
     This is a [`click`][CLICK]-powered command-line interface function,
-    and not intended for programmatic use.  Call with arguments
-    `['--help']` to see full documentation of the interface.  (See also
-    [`click.testing.CliRunner`][] for controlled, programmatic
-    invocation.)
+    and not intended for programmatic use.  See the
+    derivepassphrase-vault(1) manpage for full documentation of the
+    interface.  (See also [`click.testing.CliRunner`][] for controlled,
+    programmatic invocation.)
 
     [CLICK]: https://pypi.org/package/click/
 
@@ -1874,9 +2464,10 @@ def derivepassphrase_vault(  # noqa: C901,PLR0912,PLR0913,PLR0914,PLR0915
             `--export`, selects the format to export the current
             configuration as: JSON ("json", default) or POSIX sh ("sh").
 
-    """  # noqa: D301
+    """
     logger = logging.getLogger(PROG_NAME)
     deprecation = logging.getLogger(PROG_NAME + '.deprecation')
+    service_metavar = _msg.TranslatedString(_msg.Label.VAULT_METAVAR_SERVICE)
     options_in_group: dict[type[click.Option], list[click.Option]] = {}
     params_by_str: dict[str, click.Parameter] = {}
     for param in ctx.command.params:
@@ -1934,7 +2525,13 @@ def derivepassphrase_vault(  # noqa: C901,PLR0912,PLR0913,PLR0914,PLR0915
             param2_str = option_name(param2)
             raise click.BadOptionUsage(
                 param1_str,
-                f'{param1_str} is mutually exclusive with {param2_str}',
+                str(
+                    _msg.TranslatedString(
+                        _msg.ErrMsgTemplate.PARAMS_MUTUALLY_EXCLUSIVE,
+                        param1=param1_str,
+                        param2=param2_str,
+                    )
+                ),
                 ctx=ctx,
             )
         return
@@ -1958,37 +2555,67 @@ def derivepassphrase_vault(  # noqa: C901,PLR0912,PLR0913,PLR0914,PLR0915
             )
             new_name = os.path.basename(_config_filename(subsystem='vault'))
             deprecation.warning(
-                (
-                    'Using deprecated v0.1-style config file %r, '
-                    'instead of v0.2-style %r.  '
-                    'Support for v0.1-style config filenames will be '
-                    'removed in v1.0.'
+                _msg.TranslatedString(
+                    _msg.WarnMsgTemplate.V01_STYLE_CONFIG,
+                    old=old_name,
+                    new=new_name,
                 ),
-                old_name,
-                new_name,
             )
             if isinstance(exc, OSError):
                 logger.warning(
-                    'Failed to migrate to %r: %s: %r',
-                    new_name,
-                    exc.strerror,
-                    exc.filename,
+                    _msg.TranslatedString(
+                        _msg.WarnMsgTemplate.FAILED_TO_MIGRATE_CONFIG,
+                        path=new_name,
+                        error=exc.strerror,
+                        filename=exc.filename,
+                    ).maybe_without_filename(),
                 )
             else:
-                deprecation.info('Successfully migrated to %r.', new_name)
+                deprecation.info(
+                    _msg.TranslatedString(
+                        _msg.InfoMsgTemplate.SUCCESSFULLY_MIGRATED,
+                        path=new_name,
+                    ),
+                )
             return backup_config
         except OSError as exc:
-            err('Cannot load config: %s: %r', exc.strerror, exc.filename)
+            err(
+                _msg.TranslatedString(
+                    _msg.ErrMsgTemplate.CANNOT_LOAD_VAULT_SETTINGS,
+                    error=exc.strerror,
+                    filename=exc.filename,
+                ).maybe_without_filename(),
+            )
         except Exception as exc:  # noqa: BLE001
-            err('Cannot load config: %s', str(exc), exc_info=exc)
+            err(
+                _msg.TranslatedString(
+                    _msg.ErrMsgTemplate.CANNOT_LOAD_VAULT_SETTINGS,
+                    error=str(exc),
+                    filename=None,
+                ).maybe_without_filename(),
+                exc_info=exc,
+            )
 
     def put_config(config: _types.VaultConfig, /) -> None:
         try:
             _save_config(config)
         except OSError as exc:
-            err('Cannot store config: %s: %r', exc.strerror, exc.filename)
+            err(
+                _msg.TranslatedString(
+                    _msg.ErrMsgTemplate.CANNOT_STORE_VAULT_SETTINGS,
+                    error=exc.strerror,
+                    filename=exc.filename,
+                ).maybe_without_filename(),
+            )
         except Exception as exc:  # noqa: BLE001
-            err('Cannot store config: %s', str(exc), exc_info=exc)
+            err(
+                _msg.TranslatedString(
+                    _msg.ErrMsgTemplate.CANNOT_STORE_VAULT_SETTINGS,
+                    error=str(exc),
+                    filename=None,
+                ).maybe_without_filename(),
+                exc_info=exc,
+            )
 
     def get_user_config() -> dict[str, Any]:
         try:
@@ -1996,9 +2623,22 @@ def derivepassphrase_vault(  # noqa: C901,PLR0912,PLR0913,PLR0914,PLR0915
         except FileNotFoundError:
             return {}
         except OSError as exc:
-            err('Cannot load user config: %s: %r', exc.strerror, exc.filename)
+            err(
+                _msg.TranslatedString(
+                    _msg.ErrMsgTemplate.CANNOT_LOAD_USER_CONFIG,
+                    error=exc.strerror,
+                    filename=exc.filename,
+                ).maybe_without_filename(),
+            )
         except Exception as exc:  # noqa: BLE001
-            err('Cannot load user config: %s', str(exc), exc_info=exc)
+            err(
+                _msg.TranslatedString(
+                    _msg.ErrMsgTemplate.CANNOT_LOAD_USER_CONFIG,
+                    error=str(exc),
+                    filename=None,
+                ).maybe_without_filename(),
+                exc_info=exc,
+            )
 
     configuration: _types.VaultConfig
 
@@ -2020,15 +2660,21 @@ def derivepassphrase_vault(  # noqa: C901,PLR0912,PLR0913,PLR0914,PLR0915
         if is_param_set(param) and not (
             service or is_param_set(params_by_str['--config'])
         ):
-            opt_str = param.opts[0]
-            msg = f'{opt_str} requires a SERVICE or --config'
-            raise click.UsageError(msg)  # noqa: DOC501
+            err_msg = _msg.TranslatedString(
+                _msg.ErrMsgTemplate.PARAMS_NEEDS_SERVICE_OR_CONFIG,
+                param=param.opts[0],
+                service_metavar=service_metavar,
+            )
+            raise click.UsageError(str(err_msg))  # noqa: DOC501
     sv_options = [params_by_str['--notes'], params_by_str['--delete']]
     for param in sv_options:
         if is_param_set(param) and not service:
-            opt_str = param.opts[0]
-            msg = f'{opt_str} requires a SERVICE'
-            raise click.UsageError(msg)
+            err_msg = _msg.TranslatedString(
+                _msg.ErrMsgTemplate.PARAMS_NEEDS_SERVICE,
+                param=param.opts[0],
+                service_metavar=service_metavar,
+            )
+            raise click.UsageError(str(err_msg))
     no_sv_options = [
         params_by_str['--delete-globals'],
         params_by_str['--clear'],
@@ -2036,18 +2682,21 @@ def derivepassphrase_vault(  # noqa: C901,PLR0912,PLR0913,PLR0914,PLR0915
     ]
     for param in no_sv_options:
         if is_param_set(param) and service:
-            opt_str = param.opts[0]
-            msg = f'{opt_str} does not take a SERVICE argument'
-            raise click.UsageError(msg)
+            err_msg = _msg.TranslatedString(
+                _msg.ErrMsgTemplate.PARAMS_NO_SERVICE,
+                param=param.opts[0],
+                service_metavar=service_metavar,
+            )
+            raise click.UsageError(str(err_msg))
 
     user_config = get_user_config()
 
     if service == '':  # noqa: PLC1901
         logger.warning(
-            'An empty SERVICE is not supported by vault(1).  '
-            'For compatibility, this will be treated as if SERVICE '
-            'was not supplied, i.e., it will error out, or '
-            'operate on global settings.'
+            _msg.TranslatedString(
+                _msg.WarnMsgTemplate.EMPTY_SERVICE_NOT_SUPPORTED,
+                service_metavar=service_metavar,
+            )
         )
 
     if edit_notes:
@@ -2066,7 +2715,11 @@ def derivepassphrase_vault(  # noqa: C901,PLR0912,PLR0913,PLR0914,PLR0915
                     break
             else:
                 if not notes_value.strip():
-                    err('Not saving new notes: user aborted request')
+                    err(
+                        _msg.TranslatedString(
+                            _msg.ErrMsgTemplate.USER_ABORTED_EDIT
+                        )
+                    )
             configuration['services'].setdefault(service, {})['notes'] = (
                 notes_value.strip('\n')
             )
@@ -2104,12 +2757,32 @@ def derivepassphrase_vault(  # noqa: C901,PLR0912,PLR0913,PLR0914,PLR0915
             with infile:
                 maybe_config = json.load(infile)
         except json.JSONDecodeError as exc:
-            err('Cannot load config: cannot decode JSON: %s', exc)
+            err(
+                _msg.TranslatedString(
+                    _msg.ErrMsgTemplate.CANNOT_DECODEIMPORT_VAULT_SETTINGS,
+                    error=exc,
+                )
+            )
         except OSError as exc:
-            err('Cannot load config: %s: %r', exc.strerror, exc.filename)
+            err(
+                _msg.TranslatedString(
+                    _msg.ErrMsgTemplate.CANNOT_IMPORT_VAULT_SETTINGS,
+                    error=exc.strerror,
+                    filename=exc.filename,
+                ).maybe_without_filename()
+            )
         cleaned = _types.clean_up_falsy_vault_config_values(maybe_config)
         if not _types.is_vault_config(maybe_config):
-            err('Cannot load config: %s', _INVALID_VAULT_CONFIG)
+            err(
+                _msg.TranslatedString(
+                    _msg.ErrMsgTemplate.CANNOT_IMPORT_VAULT_SETTINGS,
+                    error=_msg.TranslatedString(
+                        _msg.ErrMsgTemplate.INVALID_VAULT_CONFIG,
+                        config=maybe_config,
+                    ),
+                    filename=None,
+                ).maybe_without_filename()
+            )
         assert cleaned is not None
         for step in cleaned:
             # These are never fatal errors, because the semantics of
@@ -2117,27 +2790,28 @@ def derivepassphrase_vault(  # noqa: C901,PLR0912,PLR0913,PLR0914,PLR0915
             # but not ill-defined.
             if step.action == 'replace':
                 logger.warning(
-                    'Replacing invalid value %s for key %s with %s.',
-                    json.dumps(step.old_value),
-                    _types.json_path(step.path),
-                    json.dumps(step.new_value),
+                    _msg.TranslatedString(
+                        _msg.WarnMsgTemplate.STEP_REPLACE_INVALID_VALUE,
+                        old=json.dumps(step.old_value),
+                        path=_types.json_path(step.path),
+                        new=json.dumps(step.new_value),
+                    ),
                 )
             else:
                 logger.warning(
-                    'Removing ineffective setting %s = %s.',
-                    _types.json_path(step.path),
-                    json.dumps(step.old_value),
+                    _msg.TranslatedString(
+                        _msg.WarnMsgTemplate.STEP_REMOVE_INEFFECTIVE_VALUE,
+                        path=_types.json_path(step.path),
+                        old=json.dumps(step.old_value),
+                    ),
                 )
         if '' in maybe_config['services']:
             logger.warning(
-                (
-                    'An empty SERVICE is not supported by vault(1), '
-                    'and the empty-string service settings will be '
-                    'inaccessible and ineffective.  To ensure that '
-                    'vault(1) and %s see the settings, move them '
-                    'into the "global" section.'
+                _msg.TranslatedString(
+                    _msg.WarnMsgTemplate.EMPTY_SERVICE_SETTINGS_INACCESSIBLE,
+                    service_metavar=service_metavar,
+                    PROG_NAME=PROG_NAME,
                 ),
-                PROG_NAME,
             )
         try:
             _check_for_misleading_passphrase(
@@ -2152,14 +2826,21 @@ def derivepassphrase_vault(  # noqa: C901,PLR0912,PLR0913,PLR0914,PLR0915
                     main_config=user_config,
                 )
         except AssertionError as exc:
-            err('The configuration file is invalid.  ' + str(exc))
+            err(
+                _msg.TranslatedString(
+                    _msg.ErrMsgTemplate.INVALID_USER_CONFIG,
+                    error=exc,
+                    filename=None,
+                ).maybe_without_filename(),
+            )
         global_obj = maybe_config.get('global', {})
         has_key = _types.js_truthiness(global_obj.get('key'))
         has_phrase = _types.js_truthiness(global_obj.get('phrase'))
         if has_key and has_phrase:
             logger.warning(
-                'Setting a global passphrase is ineffective '
-                'because a key is also set.'
+                _msg.TranslatedString(
+                    _msg.WarnMsgTemplate.GLOBAL_PASSPHRASE_INEFFECTIVE,
+                )
             )
         for service_name, service_obj in maybe_config['services'].items():
             has_key = _types.js_truthiness(
@@ -2170,11 +2851,10 @@ def derivepassphrase_vault(  # noqa: C901,PLR0912,PLR0913,PLR0914,PLR0915
             ) or _types.js_truthiness(global_obj.get('phrase'))
             if has_key and has_phrase:
                 logger.warning(
-                    (
-                        'Setting a service passphrase is ineffective '
-                        'because a key is also set: %s'
+                    _msg.TranslatedString(
+                        _msg.WarnMsgTemplate.SERVICE_PASSPHRASE_INEFFECTIVE,
+                        service=json.dumps(service_name),
                     ),
-                    json.dumps(service_name),
                 )
         if overwrite_config:
             put_config(maybe_config)
@@ -2240,7 +2920,13 @@ def derivepassphrase_vault(  # noqa: C901,PLR0912,PLR0913,PLR0914,PLR0915
                 else:
                     json.dump(configuration, outfile)
         except OSError as exc:
-            err('Cannot store config: %s: %r', exc.strerror, exc.filename)
+            err(
+                _msg.TranslatedString(
+                    _msg.ErrMsgTemplate.CANNOT_EXPORT_VAULT_SETTINGS,
+                    error=exc.strerror,
+                    filename=exc.filename,
+                ).maybe_without_filename(),
+            )
     else:
         configuration = get_config()
         # This block could be type checked more stringently, but this
@@ -2278,26 +2964,56 @@ def derivepassphrase_vault(  # noqa: C901,PLR0912,PLR0913,PLR0914,PLR0915
                     'ASCII'
                 )
             except IndexError:
-                err('No valid SSH key selected')
+                err(
+                    _msg.TranslatedString(
+                        _msg.ErrMsgTemplate.USER_ABORTED_SSH_KEY_SELECTION
+                    ),
+                )
             except KeyError:
-                err('Cannot find running SSH agent; check SSH_AUTH_SOCK')
-            except NotImplementedError:
                 err(
-                    'Cannot connect to SSH agent because '
-                    'this Python version does not support UNIX domain sockets'
+                    _msg.TranslatedString(
+                        _msg.ErrMsgTemplate.NO_SSH_AGENT_FOUND
+                    ),
+                )
+            except LookupError:
+                err(
+                    _msg.TranslatedString(
+                        _msg.ErrMsgTemplate.NO_SUITABLE_SSH_KEYS,
+                        PROG_NAME=PROG_NAME,
                     )
+                )
+            except NotImplementedError:
+                err(_msg.TranslatedString(_msg.ErrMsgTemplate.NO_AF_UNIX))
             except OSError as exc:
-                err('Cannot connect to SSH agent: %s', exc.strerror)
-            except (
-                LookupError,
-                RuntimeError,
-                ssh_agent.SSHAgentFailedError,
-            ) as exc:
-                err(str(exc))
+                err(
+                    _msg.TranslatedString(
+                        _msg.ErrMsgTemplate.CANNOT_CONNECT_TO_AGENT,
+                        error=exc.strerror,
+                        filename=exc.filename,
+                    ).maybe_without_filename(),
+                )
+            except ssh_agent.SSHAgentFailedError as exc:
+                err(
+                    _msg.TranslatedString(
+                        _msg.ErrMsgTemplate.AGENT_REFUSED_LIST_KEYS
+                    ),
+                    exc_info=exc,
+                )
+            except RuntimeError as exc:
+                err(
+                    _msg.TranslatedString(
+                        _msg.ErrMsgTemplate.CANNOT_UNDERSTAND_AGENT
+                    ),
+                    exc_info=exc,
+                )
         elif use_phrase:
             maybe_phrase = _prompt_for_passphrase()
             if not maybe_phrase:
-                err('No passphrase given')
+                err(
+                    _msg.TranslatedString(
+                        _msg.ErrMsgTemplate.USER_ABORTED_PASSPHRASE
+                    )
+                )
             else:
                 phrase = maybe_phrase
         if store_config_only:
@@ -2319,35 +3035,41 @@ def derivepassphrase_vault(  # noqa: C901,PLR0912,PLR0913,PLR0914,PLR0915
                         main_config=user_config,
                     )
                 except AssertionError as exc:
-                    err('The configuration file is invalid.  ' + str(exc))
+                    err(
+                        _msg.TranslatedString(
+                            _msg.ErrMsgTemplate.INVALID_USER_CONFIG,
+                            error=exc,
+                            filename=None,
+                        ).maybe_without_filename(),
+                    )
                 if 'key' in settings:
                     if service:
                         logger.warning(
-                            (
-                                'Setting a service passphrase is ineffective '
-                                'because a key is also set: %s'
-                            ),
-                            json.dumps(service),
+                            _msg.TranslatedString(
+                                _msg.WarnMsgTemplate.SERVICE_PASSPHRASE_INEFFECTIVE,
+                                service=json.dumps(service),
+                            )
                         )
                     else:
                         logger.warning(
-                            'Setting a global passphrase is ineffective '
-                            'because a key is also set.'
+                            _msg.TranslatedString(
+                                _msg.WarnMsgTemplate.GLOBAL_PASSPHRASE_INEFFECTIVE
+                            )
                         )
             if not view.maps[0] and not unset_settings:
                 settings_type = 'service' if service else 'global'
-                msg = (
-                    f'Cannot update {settings_type} settings without '
-                    f'actual settings'
+                err_msg = _msg.TranslatedString(
+                    _msg.ErrMsgTemplate.CANNOT_UPDATE_SETTINGS_NO_SETTINGS,
+                    settings_type=settings_type,
                 )
-                raise click.UsageError(msg)
+                raise click.UsageError(str(err_msg))
             for setting in unset_settings:
                 if setting in view.maps[0]:
-                    msg = (
-                        f'Attempted to unset and set --{setting} '
-                        f'at the same time.'
+                    err_msg = _msg.TranslatedString(
+                        _msg.ErrMsgTemplate.SET_AND_UNSET_SAME_SETTING,
+                        setting=setting,
                     )
-                    raise click.UsageError(msg)
+                    raise click.UsageError(str(err_msg))
             subtree: dict[str, Any] = (
                 configuration['services'].setdefault(service, {})  # type: ignore[assignment]
                 if service
@@ -2365,8 +3087,13 @@ def derivepassphrase_vault(  # noqa: C901,PLR0912,PLR0913,PLR0914,PLR0915
             put_config(configuration)
         else:
             if not service:
-                msg = 'SERVICE is required'
-                raise click.UsageError(msg)
+                err_msg = _msg.TranslatedString(
+                    _msg.ErrMsgTemplate.SERVICE_REQUIRED,
+                    service_metavar=_msg.TranslatedString(
+                        _msg.Label.VAULT_METAVAR_SERVICE
+                    ),
+                )
+                raise click.UsageError(str(err_msg))
             kwargs: dict[str, Any] = {
                 k: v
                 for k, v in settings.items()
@@ -2381,7 +3108,13 @@ def derivepassphrase_vault(  # noqa: C901,PLR0912,PLR0913,PLR0914,PLR0915
                         main_config=user_config,
                     )
                 except AssertionError as exc:
-                    err('The configuration file is invalid.  ' + str(exc))
+                    err(
+                        _msg.TranslatedString(
+                            _msg.ErrMsgTemplate.INVALID_USER_CONFIG,
+                            error=exc,
+                            filename=None,
+                        ).maybe_without_filename(),
+                    )
 
             # If either --key or --phrase are given, use that setting.
             # Otherwise, if both key and phrase are set in the config,
@@ -2402,11 +3135,10 @@ def derivepassphrase_vault(  # noqa: C901,PLR0912,PLR0913,PLR0914,PLR0915
             elif kwargs.get('phrase'):
                 pass
             else:
-                msg = (
-                    'No passphrase or key given on command-line '
-                    'or in configuration'
+                err_msg = _msg.TranslatedString(
+                    _msg.ErrMsgTemplate.NO_KEY_OR_PHRASE
                 )
-                raise click.UsageError(msg)
+                raise click.UsageError(str(err_msg))
             kwargs.pop('key', '')
             result = vault.Vault(**kwargs).generate(service)
             click.echo(result.decode('ASCII'))

tests/test_derivepassphrase_cli.py

Zeige Datei @ 59d73c8

@@ -295,7 +295,7 @@ class TestCLI:
             empty_stderr=True, output='Passphrase generation:\n'
         ), 'expected clean exit, and option groups in help text'
         assert result.clean_exit(
-            empty_stderr=True, output='Use NUMBER=0, e.g. "--symbol 0"'
+            empty_stderr=True, output='Use $VISUAL or $EDITOR to configure'
         ), 'expected clean exit, and option group epilog in help text'
 
     @pytest.mark.parametrize(
@@ -971,7 +971,7 @@ class TestCLI:
             )
         result = tests.ReadableResult.parse(_result)
         assert result.error_exit(
-            error='Cannot load config'
+            error='Cannot load vault settings:'
         ), 'expected error exit and known error message'
 
     @pytest.mark.parametrize(
@@ -999,7 +999,7 @@ class TestCLI:
             )
         result = tests.ReadableResult.parse(_result)
         assert result.error_exit(
-            error='Cannot load config'
+            error='Cannot load vault settings:'
         ), 'expected error exit and known error message'
 
     @pytest.mark.parametrize(
@@ -1025,7 +1025,7 @@ class TestCLI:
             )
         result = tests.ReadableResult.parse(_result)
         assert result.error_exit(
-            error='Cannot store config'
+            error='Cannot export vault settings:'
         ), 'expected error exit and known error message'
 
     @pytest.mark.parametrize(
@@ -1054,9 +1054,9 @@ class TestCLI:
             )
         result = tests.ReadableResult.parse(_result)
         assert result.error_exit(
-            error='Cannot load config'
+            error='Cannot load vault settings:'
         ) or result.error_exit(
-            error='Cannot load user config'
+            error='Cannot load user config:'
         ), 'expected error exit and known error message'
 
     def test_220_edit_notes_successfully(
@@ -1156,7 +1156,7 @@ contents go here
             )
             result = tests.ReadableResult.parse(_result)
             assert result.error_exit(
-                error='user aborted request'
+                error='the user aborted the request'
             ), 'expected known error message'
             with open(
                 cli._config_filename(subsystem='vault'), encoding='UTF-8'
@@ -1241,14 +1241,18 @@ contents go here
     @pytest.mark.parametrize(
         ['command_line', 'input', 'err_text'],
         [
-            ([], '', 'Cannot update global settings without actual settings'),
+            (
+                [],
+                '',
+                'Cannot update global settings without any given settings',
+            ),
             (
                 ['--', 'sv'],
                 '',
-                'Cannot update service settings without actual settings',
+                'Cannot update service settings without any given settings',
             ),
-            (['--phrase', '--', 'sv'], '', 'No passphrase given'),
-            (['--key'], '', 'No valid SSH key selected'),
+            (['--phrase', '--', 'sv'], '', 'No passphrase was given'),
+            (['--key'], '', 'No SSH key was selected'),
         ],
     )
     def test_225_store_config_fail(
@@ -1324,7 +1328,7 @@ contents go here
             )
         result = tests.ReadableResult.parse(_result)
         assert result.error_exit(
-            error='Cannot find running SSH agent'
+            error='Cannot find any running SSH agent'
         ), 'expected error exit and known error message'
 
     def test_225c_store_config_fail_manual_bad_ssh_agent_connection(
@@ -1345,7 +1349,7 @@ contents go here
             )
         result = tests.ReadableResult.parse(_result)
         assert result.error_exit(
-            error='Cannot connect to SSH agent'
+            error='Cannot connect to the SSH agent'
         ), 'expected error exit and known error message'
 
     @pytest.mark.parametrize('try_race_free_implementation', [True, False])
@@ -1371,7 +1375,7 @@ contents go here
             )
         result = tests.ReadableResult.parse(_result)
         assert result.error_exit(
-            error='Cannot store config'
+            error='Cannot store vault settings:'
         ), 'expected error exit and known error message'
 
     def test_225e_store_config_fail_manual_custom_error(
@@ -1427,6 +1431,89 @@ contents go here
             error='Attempted to unset and set --length at the same time.'
         ), 'expected error exit and known error message'
 
+    def test_225g_store_config_fail_manual_ssh_agent_no_keys_loaded(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+        running_ssh_agent: tests.RunningSSHAgentInfo,
+    ) -> None:
+        del running_ssh_agent
+        runner = click.testing.CliRunner(mix_stderr=False)
+        with tests.isolated_vault_config(
+            monkeypatch=monkeypatch,
+            runner=runner,
+            vault_config={'global': {'phrase': 'abc'}, 'services': {}},
+        ):
+            def func(
+                *_args: Any,
+                **_kwargs: Any,
+            ) -> list[_types.KeyCommentPair]:
+                return []
+
+            monkeypatch.setattr(ssh_agent.SSHAgentClient, 'list_keys', func)
+            _result = runner.invoke(
+                cli.derivepassphrase_vault,
+                ['--key', '--config'],
+                catch_exceptions=False,
+            )
+        result = tests.ReadableResult.parse(_result)
+        assert result.error_exit(
+            error='no keys suitable'
+        ), 'expected error exit and known error message'
+
+    def test_225h_store_config_fail_manual_ssh_agent_runtime_error(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+        running_ssh_agent: tests.RunningSSHAgentInfo,
+    ) -> None:
+        del running_ssh_agent
+        runner = click.testing.CliRunner(mix_stderr=False)
+        with tests.isolated_vault_config(
+            monkeypatch=monkeypatch,
+            runner=runner,
+            vault_config={'global': {'phrase': 'abc'}, 'services': {}},
+        ):
+            def raiser(*_args: Any, **_kwargs: Any) -> None:
+                raise ssh_agent.TrailingDataError()
+
+            monkeypatch.setattr(ssh_agent.SSHAgentClient, 'list_keys', raiser)
+            _result = runner.invoke(
+                cli.derivepassphrase_vault,
+                ['--key', '--config'],
+                catch_exceptions=False,
+            )
+        result = tests.ReadableResult.parse(_result)
+        assert result.error_exit(
+            error='violates the communications protocol.'
+        ), 'expected error exit and known error message'
+
+    def test_225i_store_config_fail_manual_ssh_agent_refuses(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+        running_ssh_agent: tests.RunningSSHAgentInfo,
+    ) -> None:
+        del running_ssh_agent
+        runner = click.testing.CliRunner(mix_stderr=False)
+        with tests.isolated_vault_config(
+            monkeypatch=monkeypatch,
+            runner=runner,
+            vault_config={'global': {'phrase': 'abc'}, 'services': {}},
+        ):
+            def func(*_args: Any, **_kwargs: Any) -> NoReturn:
+                raise ssh_agent.SSHAgentFailedError(
+                    _types.SSH_AGENT.FAILURE, b''
+                )
+
+            monkeypatch.setattr(ssh_agent.SSHAgentClient, 'list_keys', func)
+            _result = runner.invoke(
+                cli.derivepassphrase_vault,
+                ['--key', '--config'],
+                catch_exceptions=False,
+            )
+        result = tests.ReadableResult.parse(_result)
+        assert result.error_exit(
+            error='refused to'
+        ), 'expected error exit and known error message'
+
     def test_226_no_arguments(self, monkeypatch: pytest.MonkeyPatch) -> None:
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_config(
@@ -1438,7 +1525,7 @@ contents go here
             )
         result = tests.ReadableResult.parse(_result)
         assert result.error_exit(
-            error='SERVICE is required'
+            error='Deriving a passphrase requires a SERVICE'
         ), 'expected error exit and known error message'
 
     def test_226a_no_passphrase_or_key(
@@ -1456,7 +1543,7 @@ contents go here
             )
         result = tests.ReadableResult.parse(_result)
         assert result.error_exit(
-            error='No passphrase or key given'
+            error='No passphrase or key was given'
         ), 'expected error exit and known error message'
 
     def test_230_config_directory_nonexistant(
@@ -1529,7 +1616,7 @@ contents go here
             )
             result = tests.ReadableResult.parse(_result)
             assert result.error_exit(
-                error='Cannot store config'
+                error='Cannot store vault settings:'
             ), 'expected error exit and known error message'
 
     def test_230b_store_config_custom_error(
@@ -1568,7 +1655,7 @@ contents go here
                     'global': {'phrase': 'Du\u0308sseldorf'},
                     'services': {},
                 }),
-                'the $.global passphrase is not NFC-normalized',
+                'The $.global passphrase is not NFC-normalized',
                 id='global-NFC',
             ),
             pytest.param(
@@ -1581,7 +1668,7 @@ contents go here
                     }
                 }),
                 (
-                    'the $.services["weird entry name"] passphrase '
+                    'The $.services["weird entry name"] passphrase '
                     'is not NFC-normalized'
                 ),
                 id='service-weird-name-NFC',
@@ -1591,7 +1678,7 @@ contents go here
                 ['--config', '-p', '--', DUMMY_SERVICE],
                 'Du\u0308sseldorf',
                 (
-                    f'the $.services.{DUMMY_SERVICE} passphrase '
+                    f'The $.services.{DUMMY_SERVICE} passphrase '
                     f'is not NFC-normalized'
                 ),
                 id='config-NFC',
@@ -1600,7 +1687,7 @@ contents go here
                 '',
                 ['-p', '--', DUMMY_SERVICE],
                 'Du\u0308sseldorf',
-                'the interactive input passphrase is not NFC-normalized',
+                'The interactive input passphrase is not NFC-normalized',
                 id='direct-input-NFC',
             ),
             pytest.param(
@@ -1615,7 +1702,7 @@ contents go here
                     },
                     'services': {},
                 }),
-                'the $.global passphrase is not NFD-normalized',
+                'The $.global passphrase is not NFD-normalized',
                 id='global-NFD',
             ),
             pytest.param(
@@ -1631,7 +1718,7 @@ contents go here
                     },
                 }),
                 (
-                    'the $.services["weird entry name"] passphrase '
+                    'The $.services["weird entry name"] passphrase '
                     'is not NFD-normalized'
                 ),
                 id='service-weird-name-NFD',
@@ -1650,7 +1737,7 @@ contents go here
                     },
                 }),
                 (
-                    'the $.services["weird entry name 2"] passphrase '
+                    'The $.services["weird entry name 2"] passphrase '
                     'is not NFKD-normalized'
                 ),
                 id='service-weird-name-2-NFKD',
@@ -1753,7 +1840,7 @@ contents go here
             )
         result = tests.ReadableResult.parse(_result)
         assert result.error_exit(
-            error='The configuration file is invalid.'
+            error='The user configuration file is invalid.'
         ), 'expected error exit and known error message'
         assert result.error_exit(
             error=error_message
@@ -1797,7 +1884,7 @@ contents go here
             )
             result = tests.ReadableResult.parse(_result)
             assert result.error_exit(
-                error='The configuration file is invalid.'
+                error='The user configuration file is invalid.'
             ), 'expected error exit and known error message'
             assert result.error_exit(
                 error=(
@@ -2464,12 +2551,14 @@ Boo.
         skip_if_no_af_unix_support: None,
         ssh_agent_client_with_test_keys_loaded: ssh_agent.SSHAgentClient,
     ) -> None:
-        class CustomError(RuntimeError):
-            pass
+        class ErrCallback(BaseException):
+            def __init__(self, *args: Any, **kwargs: Any) -> None:
+                super().__init__(*args[:1])
+                self.args = args
+                self.kwargs = kwargs
 
         def err(*args: Any, **_kwargs: Any) -> NoReturn:
-            args = args or ('custom error message',)
-            raise CustomError(*args)
+            raise ErrCallback(*args, **_kwargs)
 
         def fail(*_args: Any, **_kwargs: Any) -> Any:
             raise ssh_agent.SSHAgentFailedError(
@@ -2477,6 +2566,9 @@ Boo.
                 b'',
             )
 
+        def fail_runtime(*_args: Any, **_kwargs: Any) -> Any:
+            raise ssh_agent.TrailingDataError()
+
         del skip_if_no_af_unix_support
         monkeypatch.setattr(ssh_agent.SSHAgentClient, 'sign', fail)
         loaded_keys = list(ssh_agent_client_with_test_keys_loaded.list_keys())
@@ -2487,42 +2579,52 @@ Boo.
                 'list_keys',
                 lambda *_a, **_kw: [],
             )
-            with pytest.raises(CustomError, match='not loaded into the agent'):
+            with pytest.raises(ErrCallback, match='not loaded into the agent'):
                 cli._key_to_phrase(loaded_key, error_callback=err)
         with monkeypatch.context() as mp:
             mp.setattr(ssh_agent.SSHAgentClient, 'list_keys', fail)
             with pytest.raises(
-                CustomError, match='SSH agent failed to complete'
+                ErrCallback, match='SSH agent failed to or refused to'
             ):
                 cli._key_to_phrase(loaded_key, error_callback=err)
         with monkeypatch.context() as mp:
-            mp.setattr(ssh_agent.SSHAgentClient, 'list_keys', err)
+            mp.setattr(ssh_agent.SSHAgentClient, 'list_keys', fail_runtime)
             with pytest.raises(
-                CustomError, match='SSH agent failed to complete'
+                ErrCallback, match='SSH agent failed to or refused to'
             ) as excinfo:
                 cli._key_to_phrase(loaded_key, error_callback=err)
-            assert excinfo.value.args
+            assert excinfo.value.kwargs
+            assert isinstance(
+                excinfo.value.kwargs['exc_info'],
+                ssh_agent.SSHAgentFailedError,
+            )
+            assert excinfo.value.kwargs['exc_info'].__context__ is not None
             assert isinstance(
-                excinfo.value.args[0], ssh_agent.SSHAgentFailedError
+                excinfo.value.kwargs['exc_info'].__context__,
+                ssh_agent.TrailingDataError,
             )
-            assert excinfo.value.args[0].__context__ is not None
-            assert isinstance(excinfo.value.args[0].__context__, CustomError)
         with monkeypatch.context() as mp:
             mp.delenv('SSH_AUTH_SOCK', raising=True)
             with pytest.raises(
-                CustomError, match='Cannot find running SSH agent'
+                ErrCallback, match='Cannot find any running SSH agent'
             ):
                 cli._key_to_phrase(loaded_key, error_callback=err)
         with monkeypatch.context() as mp:
             mp.setenv('SSH_AUTH_SOCK', os.environ['SSH_AUTH_SOCK'] + '~')
             with pytest.raises(
-                CustomError, match='Cannot connect to SSH agent'
+                ErrCallback, match='Cannot connect to the SSH agent'
             ):
                 cli._key_to_phrase(loaded_key, error_callback=err)
         with monkeypatch.context() as mp:
             mp.delattr(socket, 'AF_UNIX', raising=True)
             with pytest.raises(
-                CustomError, match='does not support UNIX domain sockets'
+                ErrCallback, match='does not support UNIX domain sockets'
+            ):
+                cli._key_to_phrase(loaded_key, error_callback=err)
+        with monkeypatch.context() as mp:
+            mp.setattr(ssh_agent.SSHAgentClient, 'sign', fail_runtime)
+            with pytest.raises(
+                ErrCallback, match='violates the communications protocol'
             ):
                 cli._key_to_phrase(loaded_key, error_callback=err)
 
@@ -2575,7 +2677,7 @@ class TestCLITransition:
             )
             result = tests.ReadableResult.parse(_result)
         assert result.clean_exit(
-            empty_stderr=True, output='Read the vault-native configuration'
+            empty_stderr=True, output='Export a vault-native configuration'
         ), 'expected clean exit, and known help text'
 
     def test_103_help_output_vault(
@@ -2596,7 +2698,7 @@ class TestCLITransition:
             empty_stderr=True, output='Passphrase generation:\n'
         ), 'expected clean exit, and option groups in help text'
         assert result.clean_exit(
-            empty_stderr=True, output='Use NUMBER=0, e.g. "--symbol 0"'
+            empty_stderr=True, output='Use $VISUAL or $EDITOR to configure'
         ), 'expected clean exit, and option group epilog in help text'
 
     @pytest.mark.parametrize(
@@ -2749,9 +2851,9 @@ class TestCLITransition:
         result = tests.ReadableResult.parse(_result)
         assert result.clean_exit(empty_stderr=False), 'expected clean exit'
         assert tests.deprecation_warning_emitted(
-            'A subcommand will be required in v1.0', caplog.record_tuples
+            'A subcommand will be required here in v1.0', caplog.record_tuples
         )
-        assert tests.warning_emitted(
+        assert tests.deprecation_warning_emitted(
             'Defaulting to subcommand "vault"', caplog.record_tuples
         )
         assert json.loads(result.output) == tests.VAULT_V03_CONFIG_DATA
@@ -2773,9 +2875,9 @@ class TestCLITransition:
             )
         result = tests.ReadableResult.parse(_result)
         assert tests.deprecation_warning_emitted(
-            'A subcommand will be required in v1.0', caplog.record_tuples
+            'A subcommand will be required here in v1.0', caplog.record_tuples
         )
-        assert tests.warning_emitted(
+        assert tests.deprecation_warning_emitted(
             'Defaulting to subcommand "vault"', caplog.record_tuples
         )
         assert result.error_exit(
@@ -2808,9 +2910,9 @@ class TestCLITransition:
             result = tests.ReadableResult.parse(_result)
         assert result.clean_exit(empty_stderr=False), 'expected clean exit'
         assert tests.deprecation_warning_emitted(
-            'A subcommand will be required in v1.0', caplog.record_tuples
+            'A subcommand will be required here in v1.0', caplog.record_tuples
         )
-        assert tests.warning_emitted(
+        assert tests.deprecation_warning_emitted(
             'Defaulting to subcommand "vault"', caplog.record_tuples
         )
         for c in charset:
@@ -2836,13 +2938,13 @@ class TestCLITransition:
             )
             result = tests.ReadableResult.parse(_result)
         assert tests.deprecation_warning_emitted(
-            'A subcommand will be required in v1.0', caplog.record_tuples
+            'A subcommand will be required here in v1.0', caplog.record_tuples
         )
-        assert tests.warning_emitted(
+        assert tests.deprecation_warning_emitted(
             'Defaulting to subcommand "vault"', caplog.record_tuples
         )
         assert result.error_exit(
-            error='SERVICE is required'
+            error='Deriving a passphrase requires a SERVICE.'
         ), 'expected error exit and known error type'
 
     def test_300_export_using_old_config_file(


...	...	@@ -295,7 +295,7 @@ class TestCLI:
295	295	empty_stderr=True, output='Passphrase generation:\n'
296	296	), 'expected clean exit, and option groups in help text'
297	297	assert result.clean_exit(
298		- empty_stderr=True, output='Use NUMBER=0, e.g. "--symbol 0"'
	298	+ empty_stderr=True, output='Use $VISUAL or $EDITOR to configure'
299	299	), 'expected clean exit, and option group epilog in help text'
300	300
301	301	@pytest.mark.parametrize(
...	...	@@ -971,7 +971,7 @@ class TestCLI:
971	971	)
972	972	result = tests.ReadableResult.parse(_result)
973	973	assert result.error_exit(
974		- error='Cannot load config'
	974	+ error='Cannot load vault settings:'
975	975	), 'expected error exit and known error message'
976	976
977	977	@pytest.mark.parametrize(
...	...	@@ -999,7 +999,7 @@ class TestCLI:
999	999	)
1000	1000	result = tests.ReadableResult.parse(_result)
1001	1001	assert result.error_exit(
1002		- error='Cannot load config'
	1002	+ error='Cannot load vault settings:'
1003	1003	), 'expected error exit and known error message'
1004	1004
1005	1005	@pytest.mark.parametrize(
...	...	@@ -1025,7 +1025,7 @@ class TestCLI:
1025	1025	)
1026	1026	result = tests.ReadableResult.parse(_result)
1027	1027	assert result.error_exit(
1028		- error='Cannot store config'
	1028	+ error='Cannot export vault settings:'
1029	1029	), 'expected error exit and known error message'
1030	1030
1031	1031	@pytest.mark.parametrize(
...	...	@@ -1054,9 +1054,9 @@ class TestCLI:
1054	1054	)
1055	1055	result = tests.ReadableResult.parse(_result)
1056	1056	assert result.error_exit(
1057		- error='Cannot load config'
	1057	+ error='Cannot load vault settings:'
1058	1058	) or result.error_exit(
1059		- error='Cannot load user config'
	1059	+ error='Cannot load user config:'
1060	1060	), 'expected error exit and known error message'
1061	1061
1062	1062	def test_220_edit_notes_successfully(
...	...	@@ -1156,7 +1156,7 @@ contents go here
1156	1156	)
1157	1157	result = tests.ReadableResult.parse(_result)
1158	1158	assert result.error_exit(
1159		- error='user aborted request'
	1159	+ error='the user aborted the request'
1160	1160	), 'expected known error message'
1161	1161	with open(
1162	1162	cli._config_filename(subsystem='vault'), encoding='UTF-8'
...	...	@@ -1241,14 +1241,18 @@ contents go here
1241	1241	@pytest.mark.parametrize(
1242	1242	['command_line', 'input', 'err_text'],
1243	1243	[
1244		- ([], '', 'Cannot update global settings without actual settings'),
	1244	+ (
	1245	+ [],
	1246	+ '',
	1247	+ 'Cannot update global settings without any given settings',
	1248	+ ),
1245	1249	(
1246	1250	['--', 'sv'],
1247	1251	'',
1248		- 'Cannot update service settings without actual settings',
	1252	+ 'Cannot update service settings without any given settings',
1249	1253	),
1250		- (['--phrase', '--', 'sv'], '', 'No passphrase given'),
1251		- (['--key'], '', 'No valid SSH key selected'),
	1254	+ (['--phrase', '--', 'sv'], '', 'No passphrase was given'),
	1255	+ (['--key'], '', 'No SSH key was selected'),
1252	1256	],
1253	1257	)
1254	1258	def test_225_store_config_fail(
...	...	@@ -1324,7 +1328,7 @@ contents go here
1324	1328	)
1325	1329	result = tests.ReadableResult.parse(_result)
1326	1330	assert result.error_exit(
1327		- error='Cannot find running SSH agent'
	1331	+ error='Cannot find any running SSH agent'
1328	1332	), 'expected error exit and known error message'
1329	1333
1330	1334	def test_225c_store_config_fail_manual_bad_ssh_agent_connection(
...	...	@@ -1345,7 +1349,7 @@ contents go here
1345	1349	)
1346	1350	result = tests.ReadableResult.parse(_result)
1347	1351	assert result.error_exit(
1348		- error='Cannot connect to SSH agent'
	1352	+ error='Cannot connect to the SSH agent'
1349	1353	), 'expected error exit and known error message'
1350	1354
1351	1355	@pytest.mark.parametrize('try_race_free_implementation', [True, False])
...	...	@@ -1371,7 +1375,7 @@ contents go here
1371	1375	)
1372	1376	result = tests.ReadableResult.parse(_result)
1373	1377	assert result.error_exit(
1374		- error='Cannot store config'
	1378	+ error='Cannot store vault settings:'
1375	1379	), 'expected error exit and known error message'
1376	1380
1377	1381	def test_225e_store_config_fail_manual_custom_error(
...	...	@@ -1427,6 +1431,89 @@ contents go here
1427	1431	error='Attempted to unset and set --length at the same time.'
1428	1432	), 'expected error exit and known error message'
1429	1433
	1434	+ def test_225g_store_config_fail_manual_ssh_agent_no_keys_loaded(
	1435	+ self,
	1436	+ monkeypatch: pytest.MonkeyPatch,
	1437	+ running_ssh_agent: tests.RunningSSHAgentInfo,
	1438	+ ) -> None:
	1439	+ del running_ssh_agent
	1440	+ runner = click.testing.CliRunner(mix_stderr=False)
	1441	+ with tests.isolated_vault_config(
	1442	+ monkeypatch=monkeypatch,
	1443	+ runner=runner,
	1444	+ vault_config={'global': {'phrase': 'abc'}, 'services': {}},
	1445	+ ):
	1446	+ def func(
	1447	+ *_args: Any,
	1448	+ **_kwargs: Any,
	1449	+ ) -> list[_types.KeyCommentPair]:
	1450	+ return []
	1451	+
	1452	+ monkeypatch.setattr(ssh_agent.SSHAgentClient, 'list_keys', func)
	1453	+ _result = runner.invoke(
	1454	+ cli.derivepassphrase_vault,
	1455	+ ['--key', '--config'],
	1456	+ catch_exceptions=False,
	1457	+ )
	1458	+ result = tests.ReadableResult.parse(_result)
	1459	+ assert result.error_exit(
	1460	+ error='no keys suitable'
	1461	+ ), 'expected error exit and known error message'
	1462	+
	1463	+ def test_225h_store_config_fail_manual_ssh_agent_runtime_error(
	1464	+ self,
	1465	+ monkeypatch: pytest.MonkeyPatch,
	1466	+ running_ssh_agent: tests.RunningSSHAgentInfo,
	1467	+ ) -> None:
	1468	+ del running_ssh_agent
	1469	+ runner = click.testing.CliRunner(mix_stderr=False)
	1470	+ with tests.isolated_vault_config(
	1471	+ monkeypatch=monkeypatch,
	1472	+ runner=runner,
	1473	+ vault_config={'global': {'phrase': 'abc'}, 'services': {}},
	1474	+ ):
	1475	+ def raiser(_args: Any, *_kwargs: Any) -> None:
	1476	+ raise ssh_agent.TrailingDataError()
	1477	+
	1478	+ monkeypatch.setattr(ssh_agent.SSHAgentClient, 'list_keys', raiser)
	1479	+ _result = runner.invoke(
	1480	+ cli.derivepassphrase_vault,
	1481	+ ['--key', '--config'],
	1482	+ catch_exceptions=False,
	1483	+ )
	1484	+ result = tests.ReadableResult.parse(_result)
	1485	+ assert result.error_exit(
	1486	+ error='violates the communications protocol.'
	1487	+ ), 'expected error exit and known error message'
	1488	+
	1489	+ def test_225i_store_config_fail_manual_ssh_agent_refuses(
	1490	+ self,
	1491	+ monkeypatch: pytest.MonkeyPatch,
	1492	+ running_ssh_agent: tests.RunningSSHAgentInfo,
	1493	+ ) -> None:
	1494	+ del running_ssh_agent
	1495	+ runner = click.testing.CliRunner(mix_stderr=False)
	1496	+ with tests.isolated_vault_config(
	1497	+ monkeypatch=monkeypatch,
	1498	+ runner=runner,
	1499	+ vault_config={'global': {'phrase': 'abc'}, 'services': {}},
	1500	+ ):
	1501	+ def func(_args: Any, *_kwargs: Any) -> NoReturn:
	1502	+ raise ssh_agent.SSHAgentFailedError(
	1503	+ _types.SSH_AGENT.FAILURE, b''
	1504	+ )
	1505	+
	1506	+ monkeypatch.setattr(ssh_agent.SSHAgentClient, 'list_keys', func)
	1507	+ _result = runner.invoke(
	1508	+ cli.derivepassphrase_vault,
	1509	+ ['--key', '--config'],
	1510	+ catch_exceptions=False,
	1511	+ )
	1512	+ result = tests.ReadableResult.parse(_result)
	1513	+ assert result.error_exit(
	1514	+ error='refused to'
	1515	+ ), 'expected error exit and known error message'
	1516	+
1430	1517	def test_226_no_arguments(self, monkeypatch: pytest.MonkeyPatch) -> None:
1431	1518	runner = click.testing.CliRunner(mix_stderr=False)
1432	1519	with tests.isolated_config(
...	...	@@ -1438,7 +1525,7 @@ contents go here
1438	1525	)
1439	1526	result = tests.ReadableResult.parse(_result)
1440	1527	assert result.error_exit(
1441		- error='SERVICE is required'
	1528	+ error='Deriving a passphrase requires a SERVICE'
1442	1529	), 'expected error exit and known error message'
1443	1530
1444	1531	def test_226a_no_passphrase_or_key(
...	...	@@ -1456,7 +1543,7 @@ contents go here
1456	1543	)
1457	1544	result = tests.ReadableResult.parse(_result)
1458	1545	assert result.error_exit(
1459		- error='No passphrase or key given'
	1546	+ error='No passphrase or key was given'
1460	1547	), 'expected error exit and known error message'
1461	1548
1462	1549	def test_230_config_directory_nonexistant(
...	...	@@ -1529,7 +1616,7 @@ contents go here
1529	1616	)
1530	1617	result = tests.ReadableResult.parse(_result)
1531	1618	assert result.error_exit(
1532		- error='Cannot store config'
	1619	+ error='Cannot store vault settings:'
1533	1620	), 'expected error exit and known error message'
1534	1621
1535	1622	def test_230b_store_config_custom_error(
...	...	@@ -1568,7 +1655,7 @@ contents go here
1568	1655	'global': {'phrase': 'Du\u0308sseldorf'},
1569	1656	'services': {},
1570	1657	}),
1571		- 'the $.global passphrase is not NFC-normalized',
	1658	+ 'The $.global passphrase is not NFC-normalized',
1572	1659	id='global-NFC',
1573	1660	),
1574	1661	pytest.param(
...	...	@@ -1581,7 +1668,7 @@ contents go here
1581	1668	}
1582	1669	}),
1583	1670	(
1584		- 'the $.services["weird entry name"] passphrase '
	1671	+ 'The $.services["weird entry name"] passphrase '
1585	1672	'is not NFC-normalized'
1586	1673	),
1587	1674	id='service-weird-name-NFC',
...	...	@@ -1591,7 +1678,7 @@ contents go here
1591	1678	['--config', '-p', '--', DUMMY_SERVICE],
1592	1679	'Du\u0308sseldorf',
1593	1680	(
1594		- f'the $.services.{DUMMY_SERVICE} passphrase '
	1681	+ f'The $.services.{DUMMY_SERVICE} passphrase '
1595	1682	f'is not NFC-normalized'
1596	1683	),
1597	1684	id='config-NFC',
...	...	@@ -1600,7 +1687,7 @@ contents go here
1600	1687	'',
1601	1688	['-p', '--', DUMMY_SERVICE],
1602	1689	'Du\u0308sseldorf',
1603		- 'the interactive input passphrase is not NFC-normalized',
	1690	+ 'The interactive input passphrase is not NFC-normalized',
1604	1691	id='direct-input-NFC',
1605	1692	),
1606	1693	pytest.param(
...	...	@@ -1615,7 +1702,7 @@ contents go here
1615	1702	},
1616	1703	'services': {},
1617	1704	}),
1618		- 'the $.global passphrase is not NFD-normalized',
	1705	+ 'The $.global passphrase is not NFD-normalized',
1619	1706	id='global-NFD',
1620	1707	),
1621	1708	pytest.param(
...	...	@@ -1631,7 +1718,7 @@ contents go here
1631	1718	},
1632	1719	}),
1633	1720	(
1634		- 'the $.services["weird entry name"] passphrase '
	1721	+ 'The $.services["weird entry name"] passphrase '
1635	1722	'is not NFD-normalized'
1636	1723	),
1637	1724	id='service-weird-name-NFD',
...	...	@@ -1650,7 +1737,7 @@ contents go here
1650	1737	},
1651	1738	}),
1652	1739	(
1653		- 'the $.services["weird entry name 2"] passphrase '
	1740	+ 'The $.services["weird entry name 2"] passphrase '
1654	1741	'is not NFKD-normalized'
1655	1742	),
1656	1743	id='service-weird-name-2-NFKD',
...	...	@@ -1753,7 +1840,7 @@ contents go here
1753	1840	)
1754	1841	result = tests.ReadableResult.parse(_result)
1755	1842	assert result.error_exit(
1756		- error='The configuration file is invalid.'
	1843	+ error='The user configuration file is invalid.'
1757	1844	), 'expected error exit and known error message'
1758	1845	assert result.error_exit(
1759	1846	error=error_message
...	...	@@ -1797,7 +1884,7 @@ contents go here
1797	1884	)
1798	1885	result = tests.ReadableResult.parse(_result)
1799	1886	assert result.error_exit(
1800		- error='The configuration file is invalid.'
	1887	+ error='The user configuration file is invalid.'
1801	1888	), 'expected error exit and known error message'
1802	1889	assert result.error_exit(
1803	1890	error=(
...	...	@@ -2464,12 +2551,14 @@ Boo.
2464	2551	skip_if_no_af_unix_support: None,
2465	2552	ssh_agent_client_with_test_keys_loaded: ssh_agent.SSHAgentClient,
2466	2553	) -> None:
2467		- class CustomError(RuntimeError):
2468		- pass
	2554	+ class ErrCallback(BaseException):
	2555	+ def __init__(self, args: Any, *kwargs: Any) -> None:
	2556	+ super().__init__(*args[:1])
	2557	+ self.args = args
	2558	+ self.kwargs = kwargs
2469	2559
2470	2560	def err(args: Any, *_kwargs: Any) -> NoReturn:
2471		- args = args or ('custom error message',)
2472		- raise CustomError(*args)
	2561	+ raise ErrCallback(args, *_kwargs)
2473	2562
2474	2563	def fail(_args: Any, *_kwargs: Any) -> Any:
2475	2564	raise ssh_agent.SSHAgentFailedError(
...	...	@@ -2477,6 +2566,9 @@ Boo.
2477	2566	b'',
2478	2567	)
2479	2568
	2569	+ def fail_runtime(_args: Any, *_kwargs: Any) -> Any:
	2570	+ raise ssh_agent.TrailingDataError()
	2571	+
2480	2572	del skip_if_no_af_unix_support
2481	2573	monkeypatch.setattr(ssh_agent.SSHAgentClient, 'sign', fail)
2482	2574	loaded_keys = list(ssh_agent_client_with_test_keys_loaded.list_keys())
...	...	@@ -2487,42 +2579,52 @@ Boo.
2487	2579	'list_keys',
2488	2580	lambda _a, *_kw: [],
2489	2581	)
2490		- with pytest.raises(CustomError, match='not loaded into the agent'):
	2582	+ with pytest.raises(ErrCallback, match='not loaded into the agent'):
2491	2583	cli._key_to_phrase(loaded_key, error_callback=err)
2492	2584	with monkeypatch.context() as mp:
2493	2585	mp.setattr(ssh_agent.SSHAgentClient, 'list_keys', fail)
2494	2586	with pytest.raises(
2495		- CustomError, match='SSH agent failed to complete'
	2587	+ ErrCallback, match='SSH agent failed to or refused to'
2496	2588	):
2497	2589	cli._key_to_phrase(loaded_key, error_callback=err)
2498	2590	with monkeypatch.context() as mp:
2499		- mp.setattr(ssh_agent.SSHAgentClient, 'list_keys', err)
	2591	+ mp.setattr(ssh_agent.SSHAgentClient, 'list_keys', fail_runtime)
2500	2592	with pytest.raises(
2501		- CustomError, match='SSH agent failed to complete'
	2593	+ ErrCallback, match='SSH agent failed to or refused to'
2502	2594	) as excinfo:
2503	2595	cli._key_to_phrase(loaded_key, error_callback=err)
2504		- assert excinfo.value.args
	2596	+ assert excinfo.value.kwargs
	2597	+ assert isinstance(
	2598	+ excinfo.value.kwargs['exc_info'],
	2599	+ ssh_agent.SSHAgentFailedError,
	2600	+ )
	2601	+ assert excinfo.value.kwargs['exc_info'].__context__ is not None
2505	2602	assert isinstance(
2506		- excinfo.value.args[0], ssh_agent.SSHAgentFailedError
	2603	+ excinfo.value.kwargs['exc_info'].__context__,
	2604	+ ssh_agent.TrailingDataError,
2507	2605	)
2508		- assert excinfo.value.args[0].__context__ is not None
2509		- assert isinstance(excinfo.value.args[0].__context__, CustomError)
2510	2606	with monkeypatch.context() as mp:
2511	2607	mp.delenv('SSH_AUTH_SOCK', raising=True)
2512	2608	with pytest.raises(
2513		- CustomError, match='Cannot find running SSH agent'
	2609	+ ErrCallback, match='Cannot find any running SSH agent'
2514	2610	):
2515	2611	cli._key_to_phrase(loaded_key, error_callback=err)
2516	2612	with monkeypatch.context() as mp:
2517	2613	mp.setenv('SSH_AUTH_SOCK', os.environ['SSH_AUTH_SOCK'] + '~')
2518	2614	with pytest.raises(
2519		- CustomError, match='Cannot connect to SSH agent'
	2615	+ ErrCallback, match='Cannot connect to the SSH agent'
2520	2616	):
2521	2617	cli._key_to_phrase(loaded_key, error_callback=err)
2522	2618	with monkeypatch.context() as mp:
2523	2619	mp.delattr(socket, 'AF_UNIX', raising=True)
2524	2620	with pytest.raises(
2525		- CustomError, match='does not support UNIX domain sockets'
	2621	+ ErrCallback, match='does not support UNIX domain sockets'
	2622	+ ):
	2623	+ cli._key_to_phrase(loaded_key, error_callback=err)
	2624	+ with monkeypatch.context() as mp:
	2625	+ mp.setattr(ssh_agent.SSHAgentClient, 'sign', fail_runtime)
	2626	+ with pytest.raises(
	2627	+ ErrCallback, match='violates the communications protocol'
2526	2628	):
2527	2629	cli._key_to_phrase(loaded_key, error_callback=err)
2528	2630
...	...	@@ -2575,7 +2677,7 @@ class TestCLITransition:
2575	2677	)
2576	2678	result = tests.ReadableResult.parse(_result)
2577	2679	assert result.clean_exit(
2578		- empty_stderr=True, output='Read the vault-native configuration'
	2680	+ empty_stderr=True, output='Export a vault-native configuration'
2579	2681	), 'expected clean exit, and known help text'
2580	2682
2581	2683	def test_103_help_output_vault(
...	...	@@ -2596,7 +2698,7 @@ class TestCLITransition:
2596	2698	empty_stderr=True, output='Passphrase generation:\n'
2597	2699	), 'expected clean exit, and option groups in help text'
2598	2700	assert result.clean_exit(
2599		- empty_stderr=True, output='Use NUMBER=0, e.g. "--symbol 0"'
	2701	+ empty_stderr=True, output='Use $VISUAL or $EDITOR to configure'
2600	2702	), 'expected clean exit, and option group epilog in help text'
2601	2703
2602	2704	@pytest.mark.parametrize(
...	...	@@ -2749,9 +2851,9 @@ class TestCLITransition:
2749	2851	result = tests.ReadableResult.parse(_result)
2750	2852	assert result.clean_exit(empty_stderr=False), 'expected clean exit'
2751	2853	assert tests.deprecation_warning_emitted(
2752		- 'A subcommand will be required in v1.0', caplog.record_tuples
	2854	+ 'A subcommand will be required here in v1.0', caplog.record_tuples
2753	2855	)
2754		- assert tests.warning_emitted(
	2856	+ assert tests.deprecation_warning_emitted(
2755	2857	'Defaulting to subcommand "vault"', caplog.record_tuples
2756	2858	)
2757	2859	assert json.loads(result.output) == tests.VAULT_V03_CONFIG_DATA
...	...	@@ -2773,9 +2875,9 @@ class TestCLITransition:
2773	2875	)
2774	2876	result = tests.ReadableResult.parse(_result)
2775	2877	assert tests.deprecation_warning_emitted(
2776		- 'A subcommand will be required in v1.0', caplog.record_tuples
	2878	+ 'A subcommand will be required here in v1.0', caplog.record_tuples
2777	2879	)
2778		- assert tests.warning_emitted(
	2880	+ assert tests.deprecation_warning_emitted(
2779	2881	'Defaulting to subcommand "vault"', caplog.record_tuples
2780	2882	)
2781	2883	assert result.error_exit(
...	...	@@ -2808,9 +2910,9 @@ class TestCLITransition:
2808	2910	result = tests.ReadableResult.parse(_result)
2809	2911	assert result.clean_exit(empty_stderr=False), 'expected clean exit'
2810	2912	assert tests.deprecation_warning_emitted(
2811		- 'A subcommand will be required in v1.0', caplog.record_tuples
	2913	+ 'A subcommand will be required here in v1.0', caplog.record_tuples
2812	2914	)
2813		- assert tests.warning_emitted(
	2915	+ assert tests.deprecation_warning_emitted(
2814	2916	'Defaulting to subcommand "vault"', caplog.record_tuples
2815	2917	)
2816	2918	for c in charset:
...	...	@@ -2836,13 +2938,13 @@ class TestCLITransition:
2836	2938	)
2837	2939	result = tests.ReadableResult.parse(_result)
2838	2940	assert tests.deprecation_warning_emitted(
2839		- 'A subcommand will be required in v1.0', caplog.record_tuples
	2941	+ 'A subcommand will be required here in v1.0', caplog.record_tuples
2840	2942	)
2841		- assert tests.warning_emitted(
	2943	+ assert tests.deprecation_warning_emitted(
2842	2944	'Defaulting to subcommand "vault"', caplog.record_tuples
2843	2945	)
2844	2946	assert result.error_exit(
2845		- error='SERVICE is required'
	2947	+ error='Deriving a passphrase requires a SERVICE.'
2846	2948	), 'expected error exit and known error type'
2847	2949
2848	2950	def test_300_export_using_old_config_file(
2849	2951