add comments & examples for translators to help them to fix bug #1001595 for their locale.

4 files changed, 125 insertions, 27 deletions

diff --git a/src/formatter-desktop.cpp b/src/formatter-desktop.cpp
index 336d2d3..dd5285d 100644
--- a/src/formatter-desktop.cpp
+++ b/src/formatter-desktop.cpp
@@ -38,11 +38,6 @@ std::string joinDateAndTimeFormatStrings(const char* date_string,
 
     if (date_string && time_string)
     {
-        /* TRANSLATORS: This is a format string passed to strftime to
-         * combine the date and the time.  The value of "%s\u2003%s"
-         * will result in a string like this in US English 12-hour time:
-         * 'Fri Jul 16 11:50 AM'. The space in between date and time is
-         * a Unicode en space (E28082 in UTF-8 hex). */
         str = date_string;
         str += "\u2003";
         str += time_string;
@@ -134,26 +129,52 @@ const gchar* DesktopFormatter::getDateFormat(bool show_day, bool show_date, bool
     const char * fmt;
 
     if (show_day && show_date && show_year)
-        /* TRANSLATORS: a strftime(3) format showing the weekday, date, and year */
+        /* Translators, please edit/rearrange these strftime(3) tokens to suit your locale!
+           That will fix bug #1001595 for your locale and make the date/time in the upper-right corner of your screen look beautiful :)
+           This format string shows the abbreviated weekday, day, abbreviated month, and year.
+           en_US example: "%a %b %e %Y" --> "Sat Oct 31 2020"
+           en_GB example: "%a %e %b %Y" --> "Sat 31 Oct 2020"
+           zh_CN example(?): "%Y年%m月%d日 周%a" --> "2020年10月31日 周六" */
         fmt = T_("%a %b %e %Y");
+
     else if (show_day && show_date)
-        /* TRANSLATORS: a strftime(3) format showing the weekday and date */
+        /* Translators, please edit/rearrange these strftime(3) tokens to suit your locale!
+           That will fix bug #1001595 for your locale and make the date/time in the upper-right corner of your screen look beautiful :)
+           This format string shows the abbreviated weekday, day, and abbreviated month.
+           en_US example: "%a %b %e" --> "Sat Oct 31"
+           en_GB example: "%a %e %b" --> "Sat 31 Oct"
+           zh_CN example(?): "%m月%d日 周%a" --> "03月27日 周六" */
         fmt = T_("%a %b %e");
-    else if (show_day && show_year)
-        /* TRANSLATORS: a strftime(3) format showing the weekday and year. */
-        fmt = T_("%a %Y");
+
     else if (show_day)
-        /* TRANSLATORS: a strftime(3) format showing the weekday. */
+        /* Translators, please edit/rearrange these strftime(3) tokens to suit your locale!
+           That will fix bug #1001595 for your locale and make the date/time in the upper-right corner of your screen look beautiful :)
+           This format string shows the abbreviated weekday.
+           zh_CN example(?): "周%a" --> "周六" */
         fmt = T_("%a");
+
     else if (show_date && show_year)
-        /* TRANSLATORS: a strftime(3) format showing the date and year */
+        /* Translators, please edit/rearrange these strftime(3) tokens to suit your locale!
+           That will fix bug #1001595 for your locale and make the date/time in the upper-right corner of your screen look beautiful :)
+           This format string shows the day, abbreviated month, and year.
+           en_US example: "%b %e %Y" --> "Oct 31 2020"
+           en_GB example: "%e %b %Y" --> "31 Oct 2020"
+           zh_CN example(?): "%Y年%m月%d日" --> "2020年10月31日" */
         fmt = T_("%b %e %Y");
+
     else if (show_date)
-        /* TRANSLATORS: a strftime(3) format showing the date */
+        /* Translators, please edit/rearrange these strftime(3) tokens to suit your locale!
+           That will fix bug #1001595 for your locale and make the date/time in the upper-right corner of your screen look beautiful :)
+           This format string shows the abbreviated month and day. 
+           en_US example: "%b %e" --> "Mar 27"
+           en_GB example: "%e %b" --> "27 Mar"
+           zh_CN example(?): "%m月%d日" --> "03月27日" */
         fmt = T_("%b %e");
+
     else if (show_year)
-        /* TRANSLATORS: a strftime(3) format showing the year */
+        /* This strftime(3) format string shows the year. */
         fmt = T_("%Y");
+
     else
         fmt = nullptr;
 
diff --git a/src/menu.cpp b/src/menu.cpp
index 6cd1585..b4b579a 100644
--- a/src/menu.cpp
+++ b/src/menu.cpp
@@ -247,7 +247,11 @@ private:
         else
             action_name = nullptr;
 
-        // add a menuitem that shows the current date
+        /* Translators, please edit/rearrange these strftime(3) tokens to suit your locale!
+           Format string for the day on the first menuitem in the datetime indicator.
+           This format string gives the full weekday, date, month, and year.
+           en_US example: "%A, %B %e %Y" --> Saturday, October 31 2020"
+           en_GB example: "%A, %e %B %Y" --> Saturday, 31 October 2020" */
         auto label = m_state->clock->localtime().format(_("%A, %e %B %Y"));
         auto item = g_menu_item_new (label.c_str(), nullptr);
         auto v = get_serialized_calendar_icon();
diff --git a/src/snap.cpp b/src/snap.cpp
index 3ab2941..9b0abee 100644
--- a/src/snap.cpp
+++ b/src/snap.cpp
@@ -244,7 +244,9 @@ bool show_notification (SnapData* data, NotifyMode mode)
     {
         notify_notification_set_hint_string(nn, "x-canonical-snap-decisions", "true");
         notify_notification_set_hint_string(nn, "x-canonical-private-button-tint", "true");
+        /* text for the alarm popup dialog's button to show the active alarm */
         notify_notification_add_action(nn, "show", _("Show"), on_snap_show, data, nullptr);
+        /* text for the alarm popup dialog's button to shut up the alarm */
         notify_notification_add_action(nn, "dismiss", _("Dismiss"), on_snap_dismiss, data, nullptr);
         g_signal_connect(G_OBJECT(nn), "closed", G_CALLBACK(on_snap_closed), data);
     }
diff --git a/src/utils.c b/src/utils.c
index c9107ce..e6d5194 100644
--- a/src/utils.c
+++ b/src/utils.c
@@ -270,30 +270,101 @@ char* generate_full_format_string_at_time (GDateTime* now,
         {
             switch (prox)
             {
-                case DATE_PROXIMITY_TODAY:    g_string_assign (ret, T_("Today")); break;
-                case DATE_PROXIMITY_TOMORROW: g_string_assign (ret, T_("Tomorrow")); break;
-                case DATE_PROXIMITY_WEEK:     g_string_assign (ret, T_("%A")); break;
-                case DATE_PROXIMITY_FAR:      g_string_assign (ret, T_("%a %d %b")); break;
+                case DATE_PROXIMITY_TODAY:
+                    g_string_assign (ret, T_("Today"));
+                    break;
+
+                case DATE_PROXIMITY_TOMORROW:
+                    g_string_assign (ret, T_("Tomorrow"));
+                    break;
+
+                case DATE_PROXIMITY_WEEK:
+                    /* This is a strftime(3) format string indicating the unabbreviated weekday. */
+                    g_string_assign (ret, T_("%A"));
+                    break;
+
+                case DATE_PROXIMITY_FAR:
+                    /* Translators, please edit/rearrange these strftime(3) tokens to suit your locale!
+                       This format string is used for showing full-day events that are over a week away.
+                       en_US example: "%a %b %d" --> "Sat Oct 31"
+                       en_GB example: "%a %d %b" --> "Sat 31 Oct"
+                       zh_CN example(?): "%m月%d日 周%a" --> "10月31日 周六" */
+                    g_string_assign (ret, T_("%a %d %b"));
+                    break;
             }
         }
         else if (is_locale_12h())
         {
             switch (prox)
             {
-                case DATE_PROXIMITY_TODAY:    g_string_assign (ret, T_("%l:%M %p")); break;
-                case DATE_PROXIMITY_TOMORROW: g_string_assign (ret, T_("Tomorrow\u2003%l:%M %p")); break;
-                case DATE_PROXIMITY_WEEK:     g_string_assign (ret, T_("%a\u2003%l:%M %p")); break;
-                case DATE_PROXIMITY_FAR:      g_string_assign (ret, T_("%a %d %b\u2003%l:%M %p")); break;
+                case DATE_PROXIMITY_TODAY:
+                    /* Translators, please edit/rearrange these strftime(3) tokens to suit your locale!
+                       This format string is used for showing, on a 12-hour clock, events/appointments that happen today.
+                       en_US example: "%l:%M %p" --> "1:00 PM" */
+                    g_string_assign (ret, T_("%l:%M %p"));
+                    break;
+
+                case DATE_PROXIMITY_TOMORROW:
+                    /* Translators, please edit/rearrange these strftime(3) tokens to suit your locale!
+                       This format string is used for showing, on a 12-hour clock, events/appointments that happen tomorrow.
+                       (\u2003 is a unicode em space which is slightly wider than a normal space.)
+                       en_US example: "Tomorrow\u2003%l:%M %p" --> "Tomorrow  1:00 PM" */
+                    g_string_assign (ret, T_("Tomorrow\u2003%l:%M %p"));
+                    break;
+
+                case DATE_PROXIMITY_WEEK:
+                    /* Translators, please edit/rearrange these strftime(3) tokens to suit your locale!
+                       This format string is used for showing, on a 12-hour clock, events/appointments that happen this week.
+                       (\u2003 is a unicode em space which is slightly wider than a normal space.)
+                       en_US example: "Tomorrow\u2003%l:%M %p" --> "Fri  1:00 PM" */
+                    g_string_assign (ret, T_("%a\u2003%l:%M %p"));
+                    break;
+
+                case DATE_PROXIMITY_FAR:
+                    /* Translators, please edit/rearrange these strftime(3) tokens to suit your locale!
+                       This format string is used for showing, on a 12-hour clock, events/appointments that happen over a week from now.
+                       (\u2003 is a unicode em space which is slightly wider than a normal space.)
+                       en_US example: "%a %d %b\u2003%l:%M %p" --> "Fri Oct 31  1:00 PM"
+                       en_GB example: "%a %b %d\u2003%l:%M %p" --> "Fri 31 Oct  1:00 PM" */
+                    g_string_assign (ret, T_("%a %d %b\u2003%l:%M %p"));
+                    break;
             }
         }
         else
         {
             switch (prox)
             {
-                case DATE_PROXIMITY_TODAY:    g_string_assign (ret, T_("%H:%M")); break;
-                case DATE_PROXIMITY_TOMORROW: g_string_assign (ret, T_("Tomorrow\u2003%H:%M")); break;
-                case DATE_PROXIMITY_WEEK:     g_string_assign (ret, T_("%a\u2003%H:%M")); break;
-                case DATE_PROXIMITY_FAR:      g_string_assign (ret, T_("%a %d %b\u2003%H:%M")); break;
+                case DATE_PROXIMITY_TODAY:
+                    /* Translators, please edit/rearrange these strftime(3) tokens to suit your locale!
+                       This format string is used for showing, on a 24-hour clock, events/appointments that happen today.
+                       en_US example: "%H:%M" --> "13:00" */
+                    g_string_assign (ret, T_("%H:%M"));
+                    break;
+
+                case DATE_PROXIMITY_TOMORROW:
+                    /* Translators, please edit/rearrange these strftime(3) tokens to suit your locale!
+                       This format string is used for showing, on a 24-hour clock, events/appointments that happen tomorrow.
+                       (\u2003 is a unicode em space which is slightly wider than a normal space.)
+                       en_US example: "Tomorrow\u2003%l:%M %p" --> "Tomorrow  13:00" */
+                    g_string_assign (ret, T_("Tomorrow\u2003%H:%M"));
+                    break;
+
+                case DATE_PROXIMITY_WEEK:
+                    /* Translators, please edit/rearrange these strftime(3) tokens to suit your locale!
+                       This format string is used for showing, on a 24-hour clock, events/appointments that happen this week.
+                       (\u2003 is a unicode em space which is slightly wider than a normal space.)
+                       en_US example: "%a\u2003%H:%M" --> "Fri  13:00" */
+                    g_string_assign (ret, T_("%a\u2003%H:%M"));
+                    break;
+
+                case DATE_PROXIMITY_FAR:
+                    /* Translators, please edit/rearrange these strftime(3) tokens to suit your locale!
+                       This format string is used for showing, on a 24-hour clock, events/appointments that happen over a week from now.
+                       (\u2003 is a unicode em space which is slightly wider than a normal space.)
+                       en_US example: "%a %d %b\u2003%H:%M" --> "Fri Oct 31  13:00"
+                       en_GB example: "%a %b %d\u2003%H:%M" --> "Fri 31 Oct  13:00" */
+                    g_string_assign (ret, T_("%a %d %b\u2003%H:%M"));
+                    break;
             }
         }