@zohodesk/i18n 1.0.0-beta.34 → 1.0.0-beta.36-murphy

package/docs/murphy/06-MURPHY_I18N_INTEGRATION.md

@@ -0,0 +1,402 @@
+# Murphy Integration in i18n Library
+
+## Overview
+
+The i18n library (`@zohodesk/i18n`) integrates with Murphy to track translation failures - when users see fallback text instead of proper translations.
+
+---
+
+## Why Track i18n Errors?
+
+```
++-------------------------------------------------------------------+
+|  THE PROBLEM: SILENT TRANSLATION FAILURES                          |
++-------------------------------------------------------------------+
+|                                                                    |
+|  Without Tracking:                                                 |
+|                                                                    |
+|  User sees: "desk.tickets.save.button"                            |
+|  Developer: Has no idea this is happening!                        |
+|                                                                    |
+|  Causes:                                                           |
+|  +-- Missing translation key                                      |
+|  +-- i18n object not initialized                                  |
+|  +-- Wrong key name used                                          |
+|  +-- Bundle not loaded                                            |
+|                                                                    |
+|  With Murphy Tracking:                                             |
+|                                                                    |
+|  User sees: "desk.tickets.save.button"                            |
+|  Murphy Dashboard: "I18N_MISSING_KEY: desk.tickets.save.button"   |
+|  Developer: Can see and fix immediately!                          |
+|                                                                    |
++-------------------------------------------------------------------+
+```
+
+---
+
+## Implementation Architecture
+
+```
++-------------------------------------------------------------------+
+|  I18N LIBRARY MURPHY INTEGRATION                                   |
++-------------------------------------------------------------------+
+|                                                                    |
+|  +-------------------------------------------------------------+  |
+|  |  errorReporter.js (NEW FILE)                                |  |
+|  |  Path: /jsapps/i18n/src/utils/errorReporter.js              |  |
+|  |                                                              |  |
+|  |  Error Types:                                                |  |
+|  |  +--------------------------------------------------------+  |  |
+|  |  | I18N_UNDEFINED_OBJECT | i18n object not initialized   |  |  |
+|  |  | I18N_MISSING_KEY      | Translation key not found     |  |  |
+|  |  | I18N_NUMERIC_FALLBACK | Numeric ID showing fallback   |  |  |
+|  |  +--------------------------------------------------------+  |  |
+|  |                                                              |  |
+|  |  Deduplication:                                              |  |
+|  |  +-- Uses Set() to track reported keys                      |  |
+|  |  +-- Each key reported only once per session                |  |
+|  |                                                              |  |
+|  |  Safety Check:                                               |  |
+|  |  +-- isMurphyAvailable() checks if global murphy exists     |  |
+|  |  +-- Silently skips if Murphy not present                   |  |
+|  +-------------------------------------------------------------+  |
+|                              |                                     |
+|                              v                                     |
+|  +-------------------------------------------------------------+  |
+|  |  Integration Points                                         |  |
+|  |                                                              |  |
+|  |  getI18NValue() (utils/index.js)                            |  |
+|  |  +-- Called for text translations                           |  |
+|  |  +-- Reports MISSING_KEY or NUMERIC_FALLBACK               |  |
+|  |                                                              |  |
+|  |  getI18NComponent() (utils/jsxTranslations.js)              |  |
+|  |  +-- Called for JSX translations with components            |  |
+|  |  +-- Reports UNDEFINED_OBJECT or MISSING_KEY               |  |
+|  +-------------------------------------------------------------+  |
+|                                                                    |
++-------------------------------------------------------------------+
+```
+
+---
+
+## Code Implementation
+
+### 1. errorReporter.js
+
+```javascript
+// Path: /jsapps/i18n/src/utils/errorReporter.js
+
+// Error types for categorization in Murphy dashboard
+export const I18N_ERROR_TYPES = {
+  UNDEFINED_OBJECT: 'I18N_UNDEFINED_OBJECT',   // i18n not initialized
+  MISSING_KEY: 'I18N_MISSING_KEY',             // Key not found
+  NUMERIC_FALLBACK: 'I18N_NUMERIC_FALLBACK'    // Numeric ID as fallback
+};
+
+// Deduplication - report each unique key only once per session
+const reportedKeys = new Set();
+
+/**
+ * Check if Murphy SDK is available globally
+ */
+function isMurphyAvailable() {
+  return typeof murphy !== 'undefined' && typeof murphy.error === 'function';
+}
+
+/**
+ * Report i18n error to Murphy
+ * @param {string} type - Error type from I18N_ERROR_TYPES
+ * @param {string} key - The i18n key that failed
+ */
+export function reportI18NError(type, key) {
+  // Deduplicate: only report each unique key once per session
+  const dedupeKey = `${type}:${key}`;
+  if (reportedKeys.has(dedupeKey)) {
+    return;
+  }
+  reportedKeys.add(dedupeKey);
+
+  // Report to Murphy if available
+  if (isMurphyAvailable()) {
+    const error = new Error(`i18n ${type}: ${key}`);
+    error.name = type;
+
+    murphy.error(error, undefined, {
+      customTags: {
+        errorType: type,
+        i18nKey: key,
+        category: 'i18n'
+      },
+      preventClientGrouping: true
+    });
+  }
+}
+
+/**
+ * Clear reported keys (useful for testing)
+ */
+export function clearReportedKeys() {
+  reportedKeys.clear();
+}
+```
+
+### 2. Integration in getI18NValue()
+
+```javascript
+// Path: /jsapps/i18n/src/utils/index.js
+
+import { reportI18NError, I18N_ERROR_TYPES } from './errorReporter';
+
+export const getI18NValue = (i18n) => (key, values) => {
+  // Check if i18n object exists
+  if (typeof i18n === 'undefined') {
+    reportI18NError(I18N_ERROR_TYPES.UNDEFINED_OBJECT, 'i18n_object');
+    return key;
+  }
+
+  // Look up translation
+  let i18nStr = i18n[key];
+
+  // If not found, report error and return fallback
+  if (i18nStr === undefined) {
+    const isNumeric = /^\d+$/.test(key);
+    reportI18NError(
+      isNumeric ? I18N_ERROR_TYPES.NUMERIC_FALLBACK : I18N_ERROR_TYPES.MISSING_KEY,
+      key
+    );
+    return getFallbackText(key);
+  }
+
+  // Process and return translation
+  return replaceI18NValuesWithRegex(unescapeUnicode(i18nStr), values);
+};
+```
+
+### 3. Integration in getI18NComponent()
+
+```javascript
+// Path: /jsapps/i18n/src/utils/jsxTranslations.js
+
+import { reportI18NError, I18N_ERROR_TYPES } from './errorReporter';
+
+export function getI18NComponent(i18n) {
+  // Check if i18n object exists
+  if (typeof i18n === 'undefined') {
+    reportI18NError(I18N_ERROR_TYPES.UNDEFINED_OBJECT, 'i18n_object_jsx');
+    return (key) => key;
+  }
+
+  return (key) => {
+    let i18nStr = i18n[key];
+
+    // If not found, report error and return fallback
+    if (i18nStr === undefined) {
+      const isNumeric = /^\d+$/.test(key);
+      reportI18NError(
+        isNumeric ? I18N_ERROR_TYPES.NUMERIC_FALLBACK : I18N_ERROR_TYPES.MISSING_KEY,
+        key
+      );
+      return getFallbackText(key);
+    }
+
+    // Process JSX translation
+    if (typeof i18nStr === 'string') {
+      i18nStr = unescapeUnicode(i18nStr);
+      const value = prepareI18NFunc({ i18nKey: i18nStr });
+      // Cache processed value
+      window.loadI18nChunk && window.loadI18nChunk({ [key]: value });
+      i18nStr = value;
+    }
+
+    return i18nStr;
+  };
+}
+```
+
+### 4. Exports from index.js
+
+```javascript
+// Path: /jsapps/i18n/src/index.js
+
+export {
+  reportI18NError,
+  clearReportedKeys,
+  I18N_ERROR_TYPES
+} from './utils/errorReporter';
+```
+
+---
+
+## Error Types Explained
+
+```
++-------------------------------------------------------------------+
+|  I18N ERROR TYPES                                                  |
++-------------------------------------------------------------------+
+|                                                                    |
+|  I18N_UNDEFINED_OBJECT                                             |
+|  +---------------------------------------------------------------+ |
+|  | When: i18n object is undefined                                | |
+|  | Cause: i18n not initialized before component render           | |
+|  | Example: getI18NValue(undefined)('key')                       | |
+|  | Action: Check i18n initialization order                       | |
+|  +---------------------------------------------------------------+ |
+|                                                                    |
+|  I18N_MISSING_KEY                                                  |
+|  +---------------------------------------------------------------+ |
+|  | When: Translation key doesn't exist in i18n object            | |
+|  | Cause: Key typo, missing translation, wrong bundle            | |
+|  | Example: i18n['tickets.wrong.key'] === undefined              | |
+|  | Action: Add translation or fix key name                       | |
+|  +---------------------------------------------------------------+ |
+|                                                                    |
+|  I18N_NUMERIC_FALLBACK                                             |
+|  +---------------------------------------------------------------+ |
+|  | When: Key is purely numeric (e.g., "12345")                   | |
+|  | Cause: Likely using ID instead of i18n key                    | |
+|  | Example: getI18NValue(i18n)('12345')                          | |
+|  | Action: Check if ID was passed instead of key                 | |
+|  +---------------------------------------------------------------+ |
+|                                                                    |
++-------------------------------------------------------------------+
+```
+
+---
+
+## Deduplication Strategy
+
+```
++-------------------------------------------------------------------+
+|  DEDUPLICATION - WHY IT MATTERS                                    |
++-------------------------------------------------------------------+
+|                                                                    |
+|  Without Deduplication:                                            |
+|  +---------------------------------------------------------------+ |
+|  | Component renders 100 times                                   | |
+|  | Each render: getI18NValue(i18n)('missing.key')                | |
+|  | Result: 100 identical errors sent to Murphy!                  | |
+|  | Murphy quota: Exceeded quickly                                 | |
+|  +---------------------------------------------------------------+ |
+|                                                                    |
+|  With Deduplication:                                               |
+|  +---------------------------------------------------------------+ |
+|  | const reportedKeys = new Set();                               | |
+|  |                                                                | |
+|  | First render:                                                 | |
+|  |   reportI18NError('MISSING_KEY', 'missing.key')               | |
+|  |   -> Adds to Set, reports to Murphy                           | |
+|  |                                                                | |
+|  | Subsequent renders:                                           | |
+|  |   reportI18NError('MISSING_KEY', 'missing.key')               | |
+|  |   -> Already in Set, skip                                     | |
+|  |                                                                | |
+|  | Result: Only 1 error reported per unique key per session!     | |
+|  +---------------------------------------------------------------+ |
+|                                                                    |
++-------------------------------------------------------------------+
+```
+
+---
+
+## Murphy Dashboard View
+
+When errors are reported, they appear in Murphy dashboard:
+
+```
++-------------------------------------------------------------------+
+|  MURPHY DASHBOARD - I18N ERRORS                                    |
++-------------------------------------------------------------------+
+|                                                                    |
+|  Filter by: category = 'i18n'                                      |
+|                                                                    |
+|  +---------------------------------------------------------------+ |
+|  | Error: I18N_MISSING_KEY: desk.tickets.save.button             | |
+|  | Tags:                                                         | |
+|  |   errorType: I18N_MISSING_KEY                                 | |
+|  |   i18nKey: desk.tickets.save.button                           | |
+|  |   category: i18n                                              | |
+|  | Count: 1,234 (unique users)                                   | |
+|  | First seen: 2024-01-15                                        | |
+|  +---------------------------------------------------------------+ |
+|                                                                    |
+|  +---------------------------------------------------------------+ |
+|  | Error: I18N_NUMERIC_FALLBACK: 7890123                         | |
+|  | Tags:                                                         | |
+|  |   errorType: I18N_NUMERIC_FALLBACK                            | |
+|  |   i18nKey: 7890123                                            | |
+|  |   category: i18n                                              | |
+|  | Count: 45 (unique users)                                      | |
+|  | First seen: 2024-01-18                                        | |
+|  +---------------------------------------------------------------+ |
+|                                                                    |
++-------------------------------------------------------------------+
+```
+
+---
+
+## Files Modified
+
+| File | Change |
+|------|--------|
+| `src/utils/errorReporter.js` | NEW - Error reporting module |
+| `src/utils/index.js` | Added reportI18NError calls in getI18NValue |
+| `src/utils/jsxTranslations.js` | Added reportI18NError calls in getI18NComponent |
+| `src/index.js` | Added exports for error reporting functions |
+
+---
+
+## Testing
+
+```javascript
+import {
+  reportI18NError,
+  clearReportedKeys,
+  I18N_ERROR_TYPES
+} from '@zohodesk/i18n';
+
+// Test: Manual error reporting
+reportI18NError(I18N_ERROR_TYPES.MISSING_KEY, 'test.key');
+
+// Test: Clear for fresh test
+clearReportedKeys();
+
+// Test: Deduplication
+reportI18NError(I18N_ERROR_TYPES.MISSING_KEY, 'same.key');
+reportI18NError(I18N_ERROR_TYPES.MISSING_KEY, 'same.key'); // Skipped
+```
+
+---
+
+## Summary
+
+```
++-------------------------------------------------------------------+
+|  I18N MURPHY INTEGRATION SUMMARY                                   |
++-------------------------------------------------------------------+
+|                                                                    |
+|  What's Tracked:                                                   |
+|  +-- Missing translation keys                                     |
+|  +-- Undefined i18n object                                        |
+|  +-- Numeric fallback (potential ID misuse)                       |
+|                                                                    |
+|  Key Features:                                                     |
+|  +-- Automatic reporting on failure                               |
+|  +-- Deduplication per session                                    |
+|  +-- Safe if Murphy not available                                 |
+|  +-- Zero overhead on success                                     |
+|                                                                    |
+|  Integration Points:                                               |
+|  +-- getI18NValue() for text translations                         |
+|  +-- getI18NComponent() for JSX translations                      |
+|                                                                    |
++-------------------------------------------------------------------+
+```
+
+---
+
+## Related Documents
+
+- [01-MURPHY_OVERVIEW.md](./01-MURPHY_OVERVIEW.md) - What is Murphy
+- [05-MURPHY_DESK_CLIENT_USAGE.md](./05-MURPHY_DESK_CLIENT_USAGE.md) - Desk client usage
+- [07-MURPHY_WHY_I18N_APPROACH.md](./07-MURPHY_WHY_I18N_APPROACH.md) - Why i18n approach