From c267e059ff57f424559efeb29676898b9eb1c52f Mon Sep 17 00:00:00 2001
From: Matt Olson <matt.olson@bigcommerce.com>
Date: Fri, 28 Jan 2022 16:19:47 -0800
Subject: [PATCH] STRF-9433: Update doc on cascade/flatten

---
 lib/translator/index.js       |  2 +-
 lib/translator/transformer.js | 56 ++++++++++++++++-------------------
 2 files changed, 27 insertions(+), 31 deletions(-)

diff --git a/lib/translator/index.js b/lib/translator/index.js
index e2de7d2..0be61b2 100644
--- a/lib/translator/index.js
+++ b/lib/translator/index.js
@@ -39,7 +39,7 @@ function Translator(acceptLanguage, allTranslations, logger = console) {
 
     /**
      * @private
-     * @type {Object.<string, string>}
+     * @type {Object.<string, string|Object>}
      *
      * Looks like this:
      * {
diff --git a/lib/translator/transformer.js b/lib/translator/transformer.js
index b26edd3..bd7463b 100644
--- a/lib/translator/transformer.js
+++ b/lib/translator/transformer.js
@@ -36,27 +36,25 @@
  *
  * The return value looks like this, assuming preferredLocales of ['fr-CA', 'en']:
  * {
- *   'fr-CA': {
- *     locale: 'fr-CA',
- *     locales: {
- *       'salutations.welcome': 'en',
- *       'salutations.hello': 'fr-CA',
- *       'salutations.bye': 'fr',
- *       items: 'en',
- *     },
- *     translations: {
- *       'salutations.welcome': 'Welcome',
- *       'salutations.hello': 'Salut {name}',
- *       'salutations.bye': 'au revoir',
- *       items: '{count, plural, one{1 Item} other{# Items}}',
- *     }
+ *   locale: 'fr-CA',
+ *   locales: {
+ *     'salutations.welcome': 'en',
+ *     'salutations.hello': 'fr-CA',
+ *     'salutations.bye': 'fr',
+ *     items: 'en',
  *   },
+ *   translations: {
+ *     'salutations.welcome': 'Welcome',
+ *     'salutations.hello': 'Salut {name}',
+ *     'salutations.bye': 'au revoir',
+ *     items: '{count, plural, one{1 Item} other{# Items}}',
+ *   }
  * }
  *
  * @param {Object.<string, Object>} allTranslations
  * @param {string[]} preferredLocales
  * @param {Object} logger
- * @returns {Object.<string, Object>} Transformed translations
+ * @returns {Object.<string, string|Object>} Transformed translations
  */
 function transform(allTranslations, preferredLocales, logger = console) {
     const flattened = flatten(allTranslations, preferredLocales, logger);
@@ -158,26 +156,24 @@ function flatten(translations, preferredLocales, logger = console) {
  *
  * The return value looks like this, assuming preferredLocales of ['fr-CA', 'en']:
  * {
- *   'fr-CA': {
- *     locale: 'fr-CA',
- *     locales: {
- *       'salutations.welcome': 'en',
- *       'salutations.hello': 'fr-CA',
- *       'salutations.bye': 'fr',
- *       items: 'en',
- *     },
- *     translations: {
- *       'salutations.welcome': 'Welcome',
- *       'salutations.hello': 'Salut {name}',
- *       'salutations.bye': 'au revoir',
- *       items: '{count, plural, one{1 Item} other{# Items}}',
- *     }
+ *   locale: 'fr-CA',
+ *   locales: {
+ *     'salutations.welcome': 'en',
+ *     'salutations.hello': 'fr-CA',
+ *     'salutations.bye': 'fr',
+ *     items: 'en',
  *   },
+ *   translations: {
+ *     'salutations.welcome': 'Welcome',
+ *     'salutations.hello': 'Salut {name}',
+ *     'salutations.bye': 'au revoir',
+ *     items: '{count, plural, one{1 Item} other{# Items}}',
+ *   }
  * }
  *
  * @param {Object.<string, Object>} translations Flattened translations
  * @param {string[]} preferredLocales Ordered list of preferred locales
- * @returns {Object.<string, Object>} Cascaded translations spec
+ * @returns {Object.<string, string|Object>} Cascaded translations spec
  */
 function cascade(translations, preferredLocales) {
     const result = { locale: preferredLocales[0], locales: {}, translations: {} };