Merge lp:~charlesk/indicator-datetime/lp-1001595 into lp:indicator-datetime/14.04

[Charles Kerr]

Improved translator comments for better time/date localization.

When I started looking into bug #100595, I didn't have to research very many languages before realizing there isn't a one-size-fits-all solution that can be addressed in the source code.

For example, the code could check nl_langinfo(D_FMT) to see whether the month or day goes first, and that would solve the MM DD YYYY <--> DD MM YYYY complaints that are part of bug #100595.

However there are all kinds of other issues and combinations, for example en zh_CN the weekday should go after the date, rather than before, and the date format is YMD rather than DMY or MDY. And there are special cases for lots of locales. Some of this can be handled by looking at nl_langinfo(), but since we have explicit combinations of date fields in indicator-datetime, we can't handle them all without a lot of guesswork.

In the end, this is best fixed on a locale-by-locale basis by the translators who actually know how their specific locale should look. However, indicator-datetime's code hasn't made this easy in the past due to sparse comments. I've expanded on them in this patch, showing examples and encouraging translators to rearrange the strftime(3) tokens as needed for their locale.

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:334
http://jenkins.qa.ubuntu.com/job/indicator-datetime-ci/220/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/indicator-datetime-trusty-amd64-ci/100
    SUCCESS: http://jenkins.qa.ubuntu.com/job/indicator-datetime-trusty-armhf-ci/100
        deb: http://jenkins.qa.ubuntu.com/job/indicator-datetime-trusty-armhf-ci/100/artifact/work/output/*zip*/output.zip

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/indicator-datetime-ci/220/rebuild

review: Approve (continuous-integration)

[Sebastien Bacher (seb128)]

looks good, thanks Charles!

review: Approve

=== modified file 'src/formatter-desktop.cpp'
--- src/formatter-desktop.cpp	2014-01-31 00:33:14 +0000
+++ src/formatter-desktop.cpp	2014-03-28 00:38:55 +0000
@@ -38,11 +38,6 @@
 
     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 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;
 
 
=== modified file 'src/menu.cpp'
--- src/menu.cpp	2014-03-24 16:18:12 +0000
+++ src/menu.cpp	2014-03-28 00:38:55 +0000
@@ -247,7 +247,11 @@
         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();
 
=== modified file 'src/snap.cpp'
--- src/snap.cpp	2014-03-21 05:22:55 +0000
+++ src/snap.cpp	2014-03-28 00:38:55 +0000
@@ -244,7 +244,9 @@
     {
         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);
     }
 
=== modified file 'src/utils.c'
--- src/utils.c	2014-03-14 16:48:06 +0000
+++ src/utils.c	2014-03-28 00:38:55 +0000
@@ -270,30 +270,101 @@
         {
             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;
             }
         }