From 181bd7bc16482655165dd10c1e8734aa470171b6 Mon Sep 17 00:00:00 2001
From: Mark Stacey <markjstacey@gmail.com>
Date: Wed, 3 Feb 2021 03:49:41 -0330
Subject: [PATCH] Require English descriptions in locale files (#10260)

The `verify-locale-strings.js` script now validates that the
descriptions from the `en` locale are also present in all other
locales.

These descriptions are intended to help with translation, and are not
meant to be translated. This check will ensure that translators don't
accidentally translate these. It also ensures they're present alongside
each translated message, which might be helpful for understanding
context.
---
 development/lib/locales.js           | 10 ++++++++++
 development/verify-locale-strings.js | 26 ++++++++++++++++++++++++--
 2 files changed, 34 insertions(+), 2 deletions(-)

diff --git a/development/lib/locales.js b/development/lib/locales.js
index 69840fc675..86f1e6ec96 100644
--- a/development/lib/locales.js
+++ b/development/lib/locales.js
@@ -37,7 +37,17 @@ function compareLocalesForMissingItems({ base, subject }) {
   return Object.keys(base).filter((key) => !subject[key])
 }
 
+function compareLocalesForMissingDescriptions({ englishLocale, targetLocale }) {
+  return Object.keys(englishLocale).filter(
+    (key) =>
+      targetLocale[key] !== undefined &&
+      englishLocale[key].description !== undefined &&
+      englishLocale[key].description !== targetLocale[key].description,
+  )
+}
+
 module.exports = {
+  compareLocalesForMissingDescriptions,
   compareLocalesForMissingItems,
   getLocale,
   getLocalePath,
diff --git a/development/verify-locale-strings.js b/development/verify-locale-strings.js
index 8356c3c3c2..7a0aa6281a 100644
--- a/development/verify-locale-strings.js
+++ b/development/verify-locale-strings.js
@@ -8,7 +8,8 @@
 //
 // This script will validate that locales have no unused messages. It will check
 // the English locale against string literals found under `ui/`, and it will check
-// other locales by comparing them to the English locale.
+// other locales by comparing them to the English locale. It will also validate
+// that non-English locales have all descriptions present in the English locale.
 //
 // A report will be printed to the console detailing any unused messages.
 //
@@ -27,6 +28,7 @@ const log = require('loglevel')
 const matchAll = require('string.prototype.matchall').getPolyfill()
 const localeIndex = require('../app/_locales/index.json')
 const {
+  compareLocalesForMissingDescriptions,
   compareLocalesForMissingItems,
   getLocale,
   getLocalePath,
@@ -129,12 +131,32 @@ async function verifyLocale(code) {
     })
   }
 
-  if (extraItems.length > 0) {
+  const missingDescriptions = compareLocalesForMissingDescriptions({
+    englishLocale,
+    targetLocale,
+  })
+
+  if (missingDescriptions.length) {
+    console.log(
+      `**${code}**: ${missingDescriptions.length} missing descriptions`,
+    )
+    log.info('Messages with missing descriptions:')
+    missingDescriptions.forEach(function (key) {
+      log.info(`  - [ ] ${key}`)
+    })
+  }
+
+  if (extraItems.length > 0 || missingDescriptions.length > 0) {
     if (fix) {
       const newLocale = { ...targetLocale }
       for (const item of extraItems) {
         delete newLocale[item]
       }
+      for (const message of Object.keys(englishLocale)) {
+        if (englishLocale[message].description && targetLocale[message]) {
+          targetLocale[message].description = englishLocale[message].description
+        }
+      }
       await writeLocale(code, newLocale)
     }
     return true