@zohodesk/i18n 1.0.0-beta.4 → 1.0.0-beta.41-murphy

package/docs/murphy/07-MURPHY_WHY_I18N_APPROACH.md

@@ -0,0 +1,391 @@
+# Why Murphy in i18n Library (Not Desk Client)
+
+## The Question
+
+When implementing Murphy error tracking for i18n failures, we had two options:
+
+1. **Option A:** Add tracking in the desk client application
+2. **Option B:** Add tracking in the i18n library itself
+
+This document explains why Option B is the correct choice.
+
+---
+
+## Option A: Murphy in Desk Client App
+
+### How It Would Work
+
+```
++-------------------------------------------------------------------+
+|  OPTION A: DESK CLIENT APPROACH (NOT RECOMMENDED)                  |
++-------------------------------------------------------------------+
+|                                                                    |
+|  // In desk client app component                                   |
+|  const text = getI18NValue(i18n, 'my.key');                       |
+|                                                                    |
+|  // Try to detect if it failed... somehow?                        |
+|  if (text === 'my.key' || text.startsWith('Missing')) {           |
+|    deskCustomError(...);  // Report to Murphy                     |
+|  }                                                                 |
+|                                                                    |
++-------------------------------------------------------------------+
+```
+
+### Problems with This Approach
+
+```
++-------------------------------------------------------------------+
+|  PROBLEM 1: WHERE TO HOOK?                                         |
++-------------------------------------------------------------------+
+|                                                                    |
+|  getI18NValue('missing.key')                                       |
+|                |                                                   |
+|                v                                                   |
+|  Returns: "missing.key" or "Missing: missing.key"                 |
+|                |                                                   |
+|                v                                                   |
+|  App receives a string - doesn't know it FAILED!                  |
+|                                                                    |
+|  Detection requires GUESSING:                                      |
+|  +---------------------------------------------------------------+ |
+|  | // HACKY: Check if result equals the key                      | |
+|  | if (result === key) { /* maybe failed? */ }                   | |
+|  |                                                                | |
+|  | // HACKY: Check for "Missing" prefix                          | |
+|  | if (result.startsWith('Missing')) { /* maybe failed? */ }     | |
+|  |                                                                | |
+|  | // FALSE POSITIVES: What if translation IS "Missing: ..."?    | |
+|  | // FALSE NEGATIVES: What if fallback format changes?          | |
+|  +---------------------------------------------------------------+ |
+|                                                                    |
++-------------------------------------------------------------------+
+
++-------------------------------------------------------------------+
+|  PROBLEM 2: EVERY APP NEEDS SAME CODE                              |
++-------------------------------------------------------------------+
+|                                                                    |
+|  Multiple apps use @zohodesk/i18n:                                 |
+|                                                                    |
+|  +-------------------+                                             |
+|  |   supportapp      | --> Must add Murphy wrapper  (duplicate)   |
+|  +-------------------+                                             |
+|           +                                                        |
+|  +-------------------+                                             |
+|  |   portal app      | --> Must add Murphy wrapper  (duplicate)   |
+|  +-------------------+                                             |
+|           +                                                        |
+|  +-------------------+                                             |
+|  |   ASAP widget     | --> Must add Murphy wrapper  (duplicate)   |
+|  +-------------------+                                             |
+|           +                                                        |
+|  +-------------------+                                             |
+|  |   future apps     | --> Must remember to add!    (easy to miss)|
+|  +-------------------+                                             |
+|                                                                    |
++-------------------------------------------------------------------+
+
++-------------------------------------------------------------------+
+|  PROBLEM 3: MAINTENANCE NIGHTMARE                                  |
++-------------------------------------------------------------------+
+|                                                                    |
+|  Scenario: i18n library changes fallback text format               |
+|                                                                    |
+|  Before: Returns "missing.key"                                     |
+|  After:  Returns "MISSING_TRANSLATION: missing.key"                |
+|                                                                    |
+|  Required action:                                                  |
+|  +-- Update supportapp detection logic                            |
+|  +-- Update portal app detection logic                            |
+|  +-- Update ASAP widget detection logic                           |
+|  +-- Update all future apps...                                    |
+|                                                                    |
+|  Risk: Inconsistent implementations, bugs, missed updates          |
+|                                                                    |
++-------------------------------------------------------------------+
+
++-------------------------------------------------------------------+
+|  PROBLEM 4: APPS WITHOUT MURPHY                                    |
++-------------------------------------------------------------------+
+|                                                                    |
+|  Some apps might not have Murphy configured:                       |
+|                                                                    |
+|  - New internal tools                                              |
+|  - Test environments                                               |
+|  - Third-party integrations                                        |
+|                                                                    |
+|  Each app must:                                                    |
+|  +-- Check if murphy exists                                       |
+|  +-- Handle the case where it doesn't                             |
+|  +-- Duplicate this safety check everywhere                       |
+|                                                                    |
++-------------------------------------------------------------------+
+```
+
+---
+
+## Option B: Murphy in i18n Library
+
+### How It Works
+
+```
++-------------------------------------------------------------------+
+|  OPTION B: I18N LIBRARY APPROACH (RECOMMENDED)                     |
++-------------------------------------------------------------------+
+|                                                                    |
+|  // Inside getI18NValue() in i18n library                          |
+|  export const getI18NValue = (i18n) => (key, values) => {          |
+|    let i18nStr = i18n[key];                                        |
+|                                                                    |
+|    if (i18nStr === undefined) {                                    |
+|      // WE KNOW IT FAILED - Right here, right now!                |
+|      reportI18NError(I18N_ERROR_TYPES.MISSING_KEY, key);          |
+|      return getFallbackText(key);                                  |
+|    }                                                               |
+|                                                                    |
+|    return processTranslation(i18nStr, values);                     |
+|  };                                                                 |
+|                                                                    |
++-------------------------------------------------------------------+
+```
+
+### Benefits of This Approach
+
+```
++-------------------------------------------------------------------+
+|  BENEFIT 1: KNOWS EXACTLY WHEN FAILURE OCCURS                      |
++-------------------------------------------------------------------+
+|                                                                    |
+|  // Inside getI18NValue()                                          |
+|  if (i18nStr === undefined) {                                      |
+|    // We are INSIDE the function that processes the key           |
+|    // We KNOW with 100% certainty it failed                       |
+|    // No guessing, no heuristics, no false positives              |
+|    reportI18NError(MISSING_KEY, key);                             |
+|  }                                                                 |
+|                                                                    |
++-------------------------------------------------------------------+
+
++-------------------------------------------------------------------+
+|  BENEFIT 2: FIX ONCE, WORKS EVERYWHERE                             |
++-------------------------------------------------------------------+
+|                                                                    |
+|                    +-------------------+                           |
+|                    |   i18n library    | <-- Fix here once        |
+|                    +--------+----------+                           |
+|                             |                                      |
+|           +-----------------+-----------------+                    |
+|           |                 |                 |                    |
+|           v                 v                 v                    |
+|   +-------------+   +-------------+   +-------------+              |
+|   | supportapp  |   | portal app  |   | ASAP widget |              |
+|   |     OK      |   |     OK      |   |     OK      |              |
+|   +-------------+   +-------------+   +-------------+              |
+|                                                                    |
+|  All apps automatically get Murphy tracking!                       |
+|  No code changes in consuming apps needed!                         |
+|                                                                    |
++-------------------------------------------------------------------+
+
++-------------------------------------------------------------------+
+|  BENEFIT 3: SAFE FOR APPS WITHOUT MURPHY                           |
++-------------------------------------------------------------------+
+|                                                                    |
+|  // errorReporter.js                                               |
+|  function isMurphyAvailable() {                                    |
+|    return typeof murphy !== 'undefined' &&                         |
+|           typeof murphy.error === 'function';                      |
+|  }                                                                 |
+|                                                                    |
+|  export function reportI18NError(type, key) {                      |
+|    // ... deduplication logic ...                                  |
+|                                                                    |
+|    if (isMurphyAvailable()) {                                      |
+|      murphy.error(...);  // Report if Murphy exists               |
+|    }                                                               |
+|    // Otherwise: silently skip - no crash, no error!              |
+|  }                                                                 |
+|                                                                    |
+|  Result:                                                           |
+|  +-- App WITH Murphy    -> Errors reported to dashboard           |
+|  +-- App WITHOUT Murphy -> Silently skipped, app works fine       |
+|                                                                    |
++-------------------------------------------------------------------+
+
++-------------------------------------------------------------------+
+|  BENEFIT 4: ZERO OVERHEAD ON HAPPY PATH                            |
++-------------------------------------------------------------------+
+|                                                                    |
+|  // Normal case: Translation exists                                |
+|  let i18nStr = i18n[key];  // "Save Ticket"                       |
+|                                                                    |
+|  if (i18nStr !== undefined) {                                      |
+|    // Happy path - no Murphy calls at all!                        |
+|    // Zero performance impact                                      |
+|    return processTranslation(i18nStr, values);                     |
+|  }                                                                 |
+|                                                                    |
+|  // Murphy only called when there's actually an error              |
+|                                                                    |
++-------------------------------------------------------------------+
+
++-------------------------------------------------------------------+
+|  BENEFIT 5: DATACENTER AGNOSTIC                                    |
++-------------------------------------------------------------------+
+|                                                                    |
+|  i18n library doesn't know or care which datacenter it's in:       |
+|                                                                    |
+|  US Server: Murphy already configured with US credentials         |
+|  JP Server: Murphy already configured with JP credentials         |
+|  IN Server: Murphy already configured with IN credentials         |
+|                                                                    |
+|  i18n library just calls: murphy.error(...)                       |
+|  Murphy SDK handles routing to correct datacenter!                |
+|                                                                    |
+|  Same code works everywhere without modification.                  |
+|                                                                    |
++-------------------------------------------------------------------+
+```
+
+---
+
+## Side-by-Side Comparison
+
+```
++-------------------------------------------------------------------+
+|  COMPARISON TABLE                                                  |
++-------------------------------------------------------------------+
+|                                                                    |
+| Aspect              | Desk Client     | i18n Library              |
+|---------------------|-----------------|---------------------------|
+| Detection accuracy  | Guessing        | 100% accurate             |
+| Implementation      | Every app       | Once in library           |
+| Maintenance         | Update all apps | Update one place          |
+| New apps            | Must remember   | Automatic                 |
+| Performance         | Extra checks    | Zero overhead on success  |
+| Murphy safety       | Each app checks | Built-in check            |
+| DC handling         | Each app config | Automatic                 |
+| Code duplication    | High            | None                      |
+|                                                                    |
++-------------------------------------------------------------------+
+```
+
+---
+
+## The Doctor Analogy
+
+```
++-------------------------------------------------------------------+
+|  DOCTOR ANALOGY                                                    |
++-------------------------------------------------------------------+
+|                                                                    |
+|  Option A (Desk Client):                                           |
+|  +---------------------------------------------------------------+ |
+|  |                                                                | |
+|  |  Patient: "I feel fine"                                       | |
+|  |                                                                | |
+|  |  App: "The i18n function returned something..."               | |
+|  |  App: "I THINK it might have failed?"                         | |
+|  |  App: "Let me guess based on the output..."                   | |
+|  |                                                                | |
+|  +---------------------------------------------------------------+ |
+|                                                                    |
+|  Option B (i18n Library):                                          |
+|  +---------------------------------------------------------------+ |
+|  |                                                                | |
+|  |  Doctor (i18n lib): "I examined the patient"                  | |
+|  |  Doctor (i18n lib): "The key doesn't exist - I KNOW this"     | |
+|  |  Doctor (i18n lib): *Reports directly to hospital (Murphy)*   | |
+|  |                                                                | |
+|  +---------------------------------------------------------------+ |
+|                                                                    |
+|  The doctor KNOWS the diagnosis.                                   |
+|  Don't ask the patient to diagnose themselves!                    |
+|                                                                    |
++-------------------------------------------------------------------+
+```
+
+---
+
+## Real-World Flow
+
+```
++-------------------------------------------------------------------+
+|  REAL-WORLD FLOW: I18N LIBRARY APPROACH                            |
++-------------------------------------------------------------------+
+|                                                                    |
+|  1. User visits page in US datacenter                             |
+|                                                                    |
+|  2. Murphy already configured:                                     |
+|     desk_urls.murphyAppDomain = "murphy.zoho.com"                 |
+|     murphy.install() already called                               |
+|                                                                    |
+|  3. React component renders:                                       |
+|     <I18N i18nKey="tickets.status.label" />                       |
+|                                                                    |
+|  4. i18n library processes:                                        |
+|     getI18NValue(i18n)('tickets.status.label')                    |
+|     -> i18n['tickets.status.label'] = undefined!                  |
+|     -> reportI18NError(MISSING_KEY, 'tickets.status.label')       |
+|     -> Returns fallback: "tickets.status.label"                   |
+|                                                                    |
+|  5. Murphy SDK sends to murphy.zoho.com:                          |
+|     {                                                              |
+|       error: "i18n I18N_MISSING_KEY: tickets.status.label",       |
+|       customTags: {                                                |
+|         errorType: "I18N_MISSING_KEY",                            |
+|         i18nKey: "tickets.status.label",                          |
+|         category: "i18n"                                          |
+|       }                                                            |
+|     }                                                              |
+|                                                                    |
+|  6. Developer sees in Murphy dashboard:                            |
+|     "Missing i18n key: tickets.status.label"                      |
+|     -> Adds translation                                           |
+|     -> User no longer sees raw key                                |
+|                                                                    |
++-------------------------------------------------------------------+
+```
+
+---
+
+## Conclusion
+
+```
++-------------------------------------------------------------------+
+|  FINAL RECOMMENDATION                                              |
++-------------------------------------------------------------------+
+|                                                                    |
+|  Murphy integration belongs in the i18n LIBRARY because:          |
+|                                                                    |
+|  1. ACCURACY:                                                      |
+|     The library knows EXACTLY when a translation fails            |
+|     No guessing or heuristics required                            |
+|                                                                    |
+|  2. DRY (Don't Repeat Yourself):                                   |
+|     One implementation serves all consuming apps                  |
+|     No code duplication                                            |
+|                                                                    |
+|  3. SAFETY:                                                        |
+|     Built-in check for Murphy availability                        |
+|     Works with or without Murphy                                   |
+|                                                                    |
+|  4. PERFORMANCE:                                                   |
+|     Zero overhead when translations exist                         |
+|     Only reports when there's an actual failure                   |
+|                                                                    |
+|  5. MAINTENANCE:                                                   |
+|     Fix once, benefits all apps                                   |
+|     New apps automatically get tracking                           |
+|                                                                    |
+|  This is the correct architectural decision.                      |
+|                                                                    |
++-------------------------------------------------------------------+
+```
+
+---
+
+## Related Documents
+
+- [05-MURPHY_DESK_CLIENT_USAGE.md](./05-MURPHY_DESK_CLIENT_USAGE.md) - How desk client uses Murphy
+- [06-MURPHY_I18N_INTEGRATION.md](./06-MURPHY_I18N_INTEGRATION.md) - i18n integration details
+- [02-MURPHY_ARCHITECTURE.md](./02-MURPHY_ARCHITECTURE.md) - Overall architecture

package/es/I18NContext.js

@@ -1,3 +1,2 @@
 import React from 'react';
-
-export var I18NContext = React.createContext();
+export const I18NContext = /*#__PURE__*/React.createContext();