feat: format warning with code and data to allow conditional logging

i18next · Dec 30, 2024 · 8fe0b03 · 8fe0b03
1 parent ff509ba
commit 8fe0b03
Show file tree

Hide file tree

Showing 4 changed files with 76 additions and 42 deletions.
diff --git a/helpers.d.ts b/helpers.d.ts
@@ -1,3 +1,12 @@
 // Internal Helpers
 export type $Tuple<T> = readonly [T?, ...T[]];
 export type $Subtract<T extends K, K> = Omit<T, keyof K>;
+
+export type ErrorCode =
+  | 'NO_I18NEXT_INSTANCE'
+  | 'NO_LANGUAGES'
+  | 'DEPRECATED_OPTION'
+  | 'TRANS_NULL_VALUE'
+  | 'TRANS_INVALID_OBJ'
+  | 'TRANS_INVALID_VAR'
+  | 'TRANS_INVALID_COMPONENTS';
diff --git a/src/TransWithoutContext.js b/src/TransWithoutContext.js
@@ -45,7 +45,9 @@ export const nodesToString = (children, i18nOptions, i18n, i18nKey) => {
       // actual e.g. lorem
       // expected e.g. lorem
       stringNode += `${child}`;
-    } else if (isValidElement(child)) {
+      return;
+    }
+    if (isValidElement(child)) {
       const { props, type } = child;
       const childPropsCount = Object.keys(props).length;
       const shouldKeepChild = keepArray.indexOf(type) > -1;
@@ -55,53 +57,57 @@ export const nodesToString = (children, i18nOptions, i18n, i18nKey) => {
         // actual e.g. lorem <br/> ipsum
         // expected e.g. lorem <br/> ipsum
         stringNode += `<${type}/>`;
-      } else if (
-        (!childChildren && (!shouldKeepChild || childPropsCount)) ||
-        props.i18nIsDynamicList
-      ) {
+        return;
+      }
+      if ((!childChildren && (!shouldKeepChild || childPropsCount)) || props.i18nIsDynamicList) {
         // actual e.g. lorem <hr className="test" /> ipsum
         // expected e.g. lorem <0></0> ipsum
         // or
         // we got a dynamic list like
         // e.g. <ul i18nIsDynamicList>{['a', 'b'].map(item => ( <li key={item}>{item}</li> ))}</ul>
         // expected e.g. "<0></0>", not e.g. "<0><0>a</0><1>b</1></0>"
         stringNode += `<${childIndex}></${childIndex}>`;
-      } else if (shouldKeepChild && childPropsCount === 1 && isString(childChildren)) {
+        return;
+      }
+      if (shouldKeepChild && childPropsCount === 1 && isString(childChildren)) {
         // actual e.g. dolor <strong>bold</strong> amet
         // expected e.g. dolor <strong>bold</strong> amet
         stringNode += `<${type}>${childChildren}</${type}>`;
-      } else {
-        // regular case mapping the inner children
-        const content = nodesToString(childChildren, i18nOptions, i18n, i18nKey);
-        stringNode += `<${childIndex}>${content}</${childIndex}>`;
+        return;
       }
-    } else if (child === null) {
-      warn(i18n, `Trans: the passed in value is invalid - seems you passed in a null child.`);
-    } else if (isObject(child)) {
+      // regular case mapping the inner children
+      const content = nodesToString(childChildren, i18nOptions, i18n, i18nKey);
+      stringNode += `<${childIndex}>${content}</${childIndex}>`;
+      return;
+    }
+    if (child === null) {
+      warn(i18n, 'TRANS_NULL_VALUE', `Passed in a null value as child`, { i18nKey });
+      return;
+    }
+    if (isObject(child)) {
       // e.g. lorem {{ value, format }} ipsum
       const { format, ...clone } = child;
       const keys = Object.keys(clone);
 
       if (keys.length === 1) {
         const value = format ? `${keys[0]}, ${format}` : keys[0];
         stringNode += `{{${value}}}`;
-      } else {
-        // not a valid interpolation object (can only contain one value plus format)
-        warn(
-          i18n,
-          `react-i18next: the passed in object contained more than one variable - the object should look like {{ value, format }} where format is optional.`,
-          child,
-          i18nKey,
-        );
+        return;
       }
-    } else {
       warn(
         i18n,
-        `Trans: the passed in value is invalid - seems you passed in a variable like {number} - please pass in variables for interpolation as full objects like {{number}}.`,
-        child,
-        i18nKey,
+        'TRANS_INVALID_OBJ',
+        `Invalid child - Object should only have keys {{ value, format }} (format is optional).`,
+        { i18nKey, child },
       );
+      return;
     }
+    warn(
+      i18n,
+      'TRANS_INVALID_VAR',
+      `Passed in a variable like {number} - pass variables for interpolation as full objects like {{number}}.`,
+      { i18nKey, child },
+    );
   });
 
   return stringNode;
@@ -336,7 +342,7 @@ const generateObjectComponents = (components, translation) => {
   return componentMap;
 };
 
-const generateComponents = (components, translation, i18n) => {
+const generateComponents = (components, translation, i18n, i18nKey) => {
   if (!components) return null;
 
   // components could be either an array or an object
@@ -351,7 +357,12 @@ const generateComponents = (components, translation, i18n) => {
 
   // if components is not an array or an object, warn the user
   // and return null
-  warnOnce(i18n, '<Trans /> component prop expects an object or an array');
+  warnOnce(
+    i18n,
+    'TRANS_INVALID_COMPONENTS',
+    `<Trans /> "components" prop expects an object or array`,
+    { i18nKey },
+  );
   return null;
 };
 
@@ -374,7 +385,12 @@ export function Trans({
   const i18n = i18nFromProps || getI18n();
 
   if (!i18n) {
-    warnOnce(i18n, 'You will need to pass in an i18next instance by using i18nextReactModule');
+    warnOnce(
+      i18n,
+      'NO_I18NEXT_INSTANCE',
+      `Trans: You need to pass in an i18next instance using i18nextReactModule`,
+      { i18nKey },
+    );
     return children;
   }
 
@@ -417,7 +433,7 @@ export function Trans({
   };
   const translation = key ? t(key, combinedTOpts) : defaultValue;
 
-  const generatedComponents = generateComponents(components, translation, i18n);
+  const generatedComponents = generateComponents(components, translation, i18n, i18nKey);
 
   const content = renderNodes(
     generatedComponents || children,

diff --git a/src/useTranslation.js b/src/useTranslation.js
@@ -35,7 +35,11 @@ export const useTranslation = (ns, props = {}) => {
   const i18n = i18nFromProps || i18nFromContext || getI18n();
   if (i18n && !i18n.reportNamespaces) i18n.reportNamespaces = new ReportNamespaces();
   if (!i18n) {
-    warnOnce(i18n, 'You will need to pass in an i18next instance by using initReactI18next');
+    warnOnce(
+      i18n,
+      'NO_I18NEXT_INSTANCE',
+      'useTranslation: You will need to pass in an i18next instance by using initReactI18next',
+    );
     const notReadyT = (k, optsOrDefaultValue) => {
       if (isString(optsOrDefaultValue)) return optsOrDefaultValue;
       if (isObject(optsOrDefaultValue) && isString(optsOrDefaultValue.defaultValue))
@@ -52,7 +56,8 @@ export const useTranslation = (ns, props = {}) => {
   if (i18n.options.react?.wait)
     warnOnce(
       i18n,
-      'It seems you are still using the old wait option, you may migrate to the new useSuspense behaviour.',
+      'DEPRECATED_OPTION',
+      'useTranslation: It seems you are still using the old wait option, you may migrate to the new useSuspense behaviour.',
     );
 
   const i18nOptions = { ...getDefaults(), ...i18n.options.react, ...props };

diff --git a/src/utils.js b/src/utils.js
@@ -1,20 +1,22 @@
-export const warn = (i18n, ...args) => {
+/** @type {(i18n:any,code:import('../helpers').ErrorCode,msg?:string, rest?:{[key:string]: any})=>void} */
+export const warn = (i18n, code, msg, rest) => {
+  const args = [msg, { code, ...(rest || {}) }];
   if (i18n?.services?.logger?.forward) {
-    i18n.services.logger.forward(args, 'warn', 'react-i18next::', true);
-  } else if (i18n?.services?.logger?.warn) {
-    if (isString(args[0])) args[0] = `react-i18next:: ${args[0]}`;
+    return i18n.services.logger.forward(args, 'warn', 'react-i18next::', true);
+  }
+  if (isString(args[0])) args[0] = `react-i18next:: ${args[0]}`;
+  if (i18n?.services?.logger?.warn) {
     i18n.services.logger.warn(...args);
   } else if (console?.warn) {
-    if (isString(args[0])) args[0] = `react-i18next:: ${args[0]}`;
     console.warn(...args);
   }
 };
-
 const alreadyWarned = {};
-export const warnOnce = (i18n, ...args) => {
-  if (isString(args[0]) && alreadyWarned[args[0]]) return;
-  if (isString(args[0])) alreadyWarned[args[0]] = new Date();
-  warn(i18n, ...args);
+/** @type {typeof warn} */
+export const warnOnce = (i18n, code, msg, rest) => {
+  if (isString(msg) && alreadyWarned[msg]) return;
+  if (isString(msg)) alreadyWarned[msg] = new Date();
+  warn(i18n, code, msg, rest);
 };
 
 // not needed right now
@@ -60,7 +62,9 @@ export const loadLanguages = (i18n, lng, ns, cb) => {
 
 export const hasLoadedNamespace = (ns, i18n, options = {}) => {
   if (!i18n.languages || !i18n.languages.length) {
-    warnOnce(i18n, 'i18n.languages were undefined or empty', i18n.languages);
+    warnOnce(i18n, 'NO_LANGUAGES', 'i18n.languages were undefined or empty', {
+      languages: i18n.languages,
+    });
     return true;
   }