GKeyFile: add API for getting locale of a string

g_key_file_get_locale_string() returns a translated string from the
keyfile.  In some cases, it may be useful to know the locale that that
string came from.

Add a new API, g_key_file_get_locale_for_key(), that returns the locale
of the string.

Include tests.

(Modified by Philip Withnall to rename the API and fix some minor review
issues. Squash in a separate test case commit.)

https://bugzilla.gnome.org/show_bug.cgi?id=605700

docs/reference/glib/glib-sections.txt

@@ -1987,6 +1987,7 @@ g_key_file_has_key
 g_key_file_get_value
 g_key_file_get_string
 g_key_file_get_locale_string
+g_key_file_get_locale_for_key
 g_key_file_get_boolean
 g_key_file_get_integer
 g_key_file_get_int64

glib/gkeyfile.c

@@ -2262,6 +2262,68 @@ g_key_file_get_locale_string (GKeyFile     *key_file,
   return translated_value;
 }
 
+/**
+ * g_key_file_get_locale_for_key:
+ * @key_file: a #GKeyFile
+ * @group_name: a group name
+ * @key: a key
+ * @locale: (nullable): a locale identifier or %NULL
+ *
+ * Returns the actual locale which the result of
+ * g_key_file_get_locale_string() or g_key_file_get_locale_string_list()
+ * came from.
+ *
+ * If calling g_key_file_get_locale_string() or
+ * g_key_file_get_locale_string_list() with exactly the same @key_file,
+ * @group_name, @key and @locale, the result of those functions will
+ * have originally been tagged with the locale that is the result of
+ * this function.
+ *
+ * Returns: (nullable): the locale from the file, or %NULL if the key was not
+ *   found or the entry in the file was was untranslated
+ *
+ * Since: 2.56
+ */
+gchar *
+g_key_file_get_locale_for_key (GKeyFile    *key_file,
+                               const gchar *group_name,
+                               const gchar *key,
+                               const gchar *locale)
+{
+  gchar **languages_allocated = NULL;
+  const gchar * const *languages;
+  gchar *result = NULL;
+  gsize i;
+
+  g_return_val_if_fail (key_file != NULL, NULL);
+  g_return_val_if_fail (group_name != NULL, NULL);
+  g_return_val_if_fail (key != NULL, NULL);
+
+  if (locale != NULL)
+    languages = languages_allocated = g_get_locale_variants (locale);
+  else
+    languages = g_get_language_names ();
+
+  for (i = 0; languages[i] != NULL; i++)
+    {
+      gchar *candidate_key, *translated_value;
+
+      candidate_key = g_strdup_printf ("%s[%s]", key, languages[i]);
+      translated_value = g_key_file_get_string (key_file, group_name, candidate_key, NULL);
+      g_free (translated_value);
+      g_free (candidate_key);
+
+      if (translated_value != NULL)
+        break;
+   }
+
+  result = g_strdup (languages[i]);
+
+  g_strfreev (languages_allocated);
+
+  return result;
+}
+
 /**
  * g_key_file_get_locale_string_list:
  * @key_file: a #GKeyFile

glib/gkeyfile.h

@@ -146,6 +146,11 @@ gchar    *g_key_file_get_locale_string      (GKeyFile             *key_file,
 					     const gchar          *key,
 					     const gchar          *locale,
 					     GError              **error) G_GNUC_MALLOC;
+GLIB_AVAILABLE_IN_2_56
+gchar    *g_key_file_get_locale_for_key     (GKeyFile             *key_file,
+                                             const gchar          *group_name,
+                                             const gchar          *key,
+                                             const gchar          *locale) G_GNUC_MALLOC;
 GLIB_AVAILABLE_IN_ALL
 void      g_key_file_set_locale_string      (GKeyFile             *key_file,
 					     const gchar          *group_name,

glib/tests/keyfile.c

@@ -67,6 +67,20 @@ check_locale_string_value (GKeyFile    *keyfile,
   g_free (value);
 }
 
+static void
+check_string_locale_value (GKeyFile    *keyfile,
+                           const gchar *group,
+                           const gchar *key,
+                           const gchar *locale,
+                           const gchar *expected)
+{
+  gchar *value;
+
+  value = g_key_file_get_locale_for_key (keyfile, group, key, locale);
+  g_assert_cmpstr (value, ==, expected);
+  g_free (value);
+}
+
 static void
 check_string_list_value (GKeyFile    *keyfile,
                          const gchar *group,
@@ -1686,6 +1700,32 @@ test_bytes (void)
   g_key_file_free (kf);
 }
 
+static void
+test_get_locale (void)
+{
+  GKeyFile *kf;
+
+  kf = g_key_file_new ();
+  g_key_file_load_from_data (kf,
+                             "[Group]\n"
+                             "x[fr_CA]=a\n"
+                             "x[fr]=b\n"
+                             "x=c\n",
+                             -1, G_KEY_FILE_KEEP_TRANSLATIONS,
+                             NULL);
+
+  check_locale_string_value (kf, "Group", "x", "fr_CA", "a");
+  check_string_locale_value (kf, "Group", "x", "fr_CA", "fr_CA");
+
+  check_locale_string_value (kf, "Group", "x", "fr_CH", "b");
+  check_string_locale_value (kf, "Group", "x", "fr_CH", "fr");
+
+  check_locale_string_value (kf, "Group", "x", "eo", "c");
+  check_string_locale_value (kf, "Group", "x", "eo", NULL);
+
+  g_key_file_free (kf);
+}
+
 int
 main (int argc, char *argv[])
 {
@@ -1730,6 +1770,7 @@ main (int argc, char *argv[])
   g_test_add_func ("/keyfile/utf8", test_utf8);
   g_test_add_func ("/keyfile/roundtrip", test_roundtrip);
   g_test_add_func ("/keyfile/bytes", test_bytes);
+  g_test_add_func ("/keyfile/get-locale", test_get_locale);
 
   return g_test_run ();
 }