From fb83ad326bf52f8dbc4382949a93496e1026582f Mon Sep 17 00:00:00 2001
From: Adriaan de Groot <groot@kde.org>
Date: Sat, 13 Apr 2024 23:30:57 +0200
Subject: [PATCH] [libcalamares] Document recommended translation contexts

Jobs have specific contexts for their different strings.
Many jobs (now) misuse prettyName() as a status message,
although the existing fallback mechanism means that the
name gets used as if it is a status message when the job
does not define a description or status.
---
 src/libcalamares/Job.h | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/src/libcalamares/Job.h b/src/libcalamares/Job.h
index 241b2883c..fe678fa63 100644
--- a/src/libcalamares/Job.h
+++ b/src/libcalamares/Job.h
@@ -109,12 +109,23 @@ public:
      * which of the jobs is "heavy" and which is not.
      */
     virtual int getJobWeight() const;
+
     /** @brief The human-readable name of this job
      *
      * This should be a very short statement of what the job does.
      * For status and state information, see prettyStatusMessage().
+     *
+     * The job's name may be similar to the status message, but this is
+     * a name, and should not be an active verb phrase. The translation
+     * should use context @c @label .
+     *
+     * The name of the job is used as a **fallback** when the status
+     * or descriptions are empty. If a job has no implementation of
+     * those methods, it is OK to use other contexts, but it may look
+     * strange in some places in the UI.
      */
     virtual QString prettyName() const = 0;
+
     /** @brief a longer human-readable description of what the job will do
      *
      * This **may** be used by view steps to fill in the summary
@@ -122,15 +133,23 @@ public:
      * module does so.
      *
      * The default implementation returns an empty string.
+     *
+     * The translation should use context @c @title .
      */
     virtual QString prettyDescription() const;
+
     /** @brief A human-readable status for progress reporting
      *
      * This is called from the JobQueue when progress is made, and should
      * return a not-too-long description of the job's status. This
      * is made visible in the progress bar of the execution view step.
+     *
+     * The job's status should say **what** the job is doing. It should be in
+     * present active tense. Typically the translation uses tr() context
+     * @c @status . See prettyName() for examples.
      */
     virtual QString prettyStatusMessage() const;
+
     virtual JobResult exec() = 0;
 
     bool isEmergency() const { return m_emergency; }