Bug 1962432 - Add an available locales record type for search-config-v2. r=jteow,search-reviewers

Differential Revision: https://phabricator.services.mozilla.com/D246629

toolkit/components/search/docs/SearchConfigurationSchema.rst

@@ -355,6 +355,36 @@ Example:
 This would result in the order: ``c-engine``, ``b-engine``, ``a-engine`` for the
 distribution ``distro``.
 
+Locale Fallbacks
+================
+
+On desktop, the locale provided for the user's environment matches the locales that
+are shipped with Firefox. The current list of possibilities may be found in the
+:searchfox:`all-locales file <browser/locales/all-locales>`. These are typically
+two-letter locale names, with some variants.
+
+On mobile platforms, the locales are typically language and region, e.g. ``de-DE``
+and ``de-AT``. To match with the locales on desktop, we need to implement a fallback
+routine to map the locales to those that desktop uses. For example, ``de-DE``
+needs to map to ``de``, but ``en-CA`` would stay as it is.
+
+Whilst this could be managed by looking through the full search configuration for
+all the locales referenced, this would incur a runtime cost on every startup and
+parsing of the configuration. Hence we have introduced the ``availableLocales``
+record which is a list of all the locales currently referenced in the search
+configuration.
+
+When determining the user's locale to compare with the environments within the
+configuration, the following algorithm is used by the search engine selector:
+
+#. If the user's locale matches one in the ``availableLocales``, then the user's
+   locale is used unchanged.
+
+#. If the user's locale is of the form ``ab-CD`` and the ``ab`` part matches one
+   in ``availableLocales``, then the two-letter form is used.
+
+#. Otherwise, the locale used doesn't matter, and either form may be used.
+
 .. _schema itself: https://searchfox.org/mozilla-central/source/toolkit/components/search/schema/
 .. _the version comparator: https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/version/format
 .. _search-config-v2: https://searchfox.org/mozilla-central/source/services/settings/dumps/main/search-config-v2.json

toolkit/components/search/schema/search-config-v2-schema.json

@@ -5,7 +5,7 @@
     "recordType": {
       "title": "Record Type",
       "description": "The type of details that this record contains.",
-      "enum": ["engine", "defaultEngines", "engineOrders"]
+      "enum": ["engine", "defaultEngines", "engineOrders", "availableLocales"]
     },
     "environment": {
       "title": "Environment",
@@ -469,6 +469,34 @@
         },
         "required": ["recordType", "orders"]
       }
+    },
+    {
+      "if": {
+        "properties": {
+          "recordType": {
+            "const": "availableLocales"
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "recordType": {
+            "$ref": "#/definitions/recordType"
+          },
+          "locales": {
+            "title": "Locales",
+            "description": "All locales listed in the 'locales' field of each engine record. This is used so that we can choose the correct fallback locales on mobile which generally supplies locales of the form ab-CD. This record is an optimisation so that we can avoid parsing the configuration each time for all the locales.",
+            "type": "array",
+            "items": {
+              "type": "string",
+              "pattern": "^(?:[a-z]{2,3}(-[a-zA-Z]{2,})?(?:-macos)?|default)$",
+              "minLength": 2
+            },
+            "uniqueItems": true
+          }
+        },
+        "required": ["recordType", "locales"]
+      }
     }
   ]
 }