WDP Part 8: Internationalization (i18n)

E.Auth.Token.001

Ay75d

xxHash64("E.Auth.Token.001", seed="wdp-v1") → Base62 → Ay75d

// Canonical code (English)
const canonical = "E.Auth.Token.001";

// Compute hash
const hash = xxHash64(canonical, seed: "wdp-v1");
const compactId = base62Encode(hash).substring(0, 5);
// → "Ay75d"

// This hash is the same regardless of user's language!

// catalog-en.json
{
  "E.Auth.Token.001": {
    "compact_id": "Ay75d"  // ← Same hash
  }
}

// catalog-ja.json
{
  "E.Auth.Token.001": {
    "compact_id": "Ay75d"  // ← Same hash
  }
}

catalogs/
  catalog-en.json    # English
  catalog-ja.json    # Japanese
  catalog-zh.json    # Chinese (Simplified)
  catalog-zh-TW.json # Chinese (Traditional)
  catalog-es.json    # Spanish
  catalog-fr.json    # French
  catalog-de.json    # German
  catalog-ar.json    # Arabic

catalog-{locale}.json

{
  "wdp_version": "1.0",
  "locale": "ja",
  "namespace": "myapp",
  "diags": {
    "Ay75d": {
      "code": "E.Auth.Token.001",
      "alias": "E.認証.トークン.001",
      "message": "トークンは{{timestamp}}に期限切れになりました",
      "description": "セッションの有効期限が切れました",
      "hints": [
        "もう一度ログインしてください",
        "セッションは30分後に期限切れになります"
      ]
    },
    "mN3Yr": {
      "code": "E.Auth.Password.002",
      "alias": "E.認証.パスワード.002",
      "message": "パスワードが正しくありません（残り{{attempts}}回）",
      "description": "入力されたパスワードが正しくありません",
      "hints": [
        "パスワードを確認してください",
        "大文字と小文字を区別します"
      ]
    }
  }
}

{
  "diags": {
    "Ay75d": {  // ← Compact ID as key - REQUIRED
      "code": "E.Auth.Token.001",  // ← Canonical (English) - REQUIRED
      "alias": "E.認証.トークン.001"  // ← Display (localized)
    }
  }
}

// Invalid - MUST use compact ID as key
{
  "diags": {
    "E.Auth.Token.001": { ... },  // Invalid: MUST use compact ID
    "E.認証.トークン.001": { ... }  // Invalid: MUST use compact ID
  }
}

Severity.Component.Primary.Sequence

// Display in UI
const emoji = getSeverityEmoji('E');  // Returns error emoji (❌)
const display = `${emoji} ${alias}`;  // Example: "❌ E.認証.トークン.001"

// User reports: "E.認証.トークン.001"
const canonical = lookupCanonical("E.認証.トークン.001", locale="ja");
// → "E.Auth.Token.001"

const compactId = lookupCompactId(canonical);
// → "Ay75d"

const aliases = lookupAliases("E.Auth.Token.001");
// → {
//   en: "E.Auth.Token.001",
//   ja: "E.認証.トークン.001",
//   zh: "E.认证.令牌.001"
// }

{
  "E.Auth.Token.001": {
    "message": "Token expired at {{timestamp}}"
  }
}

// catalog-en.json
{
  "message": "Token expired at {{timestamp}}"
}

// catalog-ja.json
{
  "message": "トークンは{{timestamp}}に期限切れになりました"
}

// catalog-zh.json
{
  "message": "令牌已在{{timestamp}}过期"
}

// catalog-es.json
{
  "message": "El token expiró en {{timestamp}}"
}

{
  "message": "User {{username}} logged in at {{timestamp}}"
}

{
  "message": "User {username} logged in at {timestamp}"  // Invalid: must use double braces
}

const template = "Token expired at {{timestamp}}";
const fields = { timestamp: "2024-01-15T10:30:00Z" };

const message = template.replace(/\{\{(\w+)\}\}/g, (_, field) => 
  fields[field] || `{{${field}}}`
);

// → "Token expired at 2024-01-15T10:30:00Z"

{
  "message": "Quota is {{quota_percent}}% full"
}

{
  "message": "Quota is {{quota_used * 100 / quota_limit}}% full"  // Invalid: expressions not supported
}

{
  "compact_id": "wN4Qm",
  "fields": {
    "quota_used": "850",
    "quota_limit": "1000",
    "quota_percent": "85"  // ← Server calculates this
  }
}

// RECOMMENDED (language-agnostic)
{
  "diags": {
    "Ay75d": {
      "code": "E.Auth.Token.001",
      "alias": "E.認証.トークン.001",
      "message": "トークンは{{timestamp}}に期限切れになりました"
    }
  }
}

// NOT RECOMMENDED for i18n (English-centric)
{
  "diags": {
    "xK4Np": {
      "code": "E.Auth.Token.EXPIRED",
      "alias": "E.認証.トークン.EXPIRED",
      "message": "トークンは{{timestamp}}に期限切れになりました"
    }
  }
}

E.Auth.Token.EXPIRED

{
  "diags": {
    "xK4Np": {
      "code": "E.Auth.Token.EXPIRED",
      "aliases": {
        "en": "E.Auth.Token.EXPIRED",
        "fr": "E.Auth.Jeton.EXPIRE",              // French with SCREAMING_SNAKE_CASE
        "es": "E.Aut.Token.EXPIRADO",             // Spanish with SCREAMING_SNAKE_CASE
        "de": "E.Auth.Token.ABGELAUFEN",          // German with SCREAMING_SNAKE_CASE
        "pt": "E.Auth.Token.EXPIRADO",            // Portuguese with SCREAMING_SNAKE_CASE
        "ru": "E.Auth.Token.ИСТЕК",               // Russian (Cyrillic) with uppercase
        "el": "E.Auth.Token.ΕΛΗΞΕ"                // Greek with uppercase
      }
    }
  }
}

{
  "diags": {
    "xK4Np": {
      "code": "E.Auth.Token.EXPIRED",
      "aliases": {
        "ja": "E.認証.トークン.期限切れ",          // Note: No case available
        "zh": "E.认证.令牌.过期",                  // Note: No case available
        "ar": "E.Auth.Token.EXPIRED",            // Note: Could keep English or use Arabic
        "he": "E.Auth.Token.תוקף_פג",             // Note: Hebrew, no case
        "th": "E.Auth.Token.หมดอายุ",              // Note: Thai, no case
        "hi": "E.Auth.Token.समाप्त"               // Note: Hindi (Devanagari), no case
      }
    }
  }
}

// catalog-en.json
{
  "diags": {
    "vR2Lq": {
      "code": "E.Validation.Items.001",
      "alias": "E.Validation.Items.001",
      "message": "{count, plural, one {# item failed} other {# items failed}}"
    }
  }
}

// catalog-ja.json (Japanese doesn't pluralize)
{
  "diags": {
    "vR2Lq": {
      "code": "E.Validation.Items.001",
      "alias": "E.検証.アイテム.001",
      "message": "{{count}}個のアイテムが失敗しました"
    }
  }
}

// catalog-pl.json (Polish has complex plural rules)
{
  "diags": {
    "vR2Lq": {
      "code": "E.Validation.Items.001",
      "alias": "E.Walidacja.Elementy.001",
      "message": "{count, plural, one {# element nie powiódł się} few {# elementy nie powiodły się} many {# elementów nie powiodło się}}"
    }
  }
}

// wdp.config.json
{
  "wdp": {
    "primary_locale": "ja",
    "supported_locales": ["ja", "en", "zh", "fr"]
  }
}

# README.md

## Internationalization

Primary language: Japanese (`catalog-ja.json`)
All translations are made from Japanese.

// catalog-ja.json (primary)
{
  "E.Auth.Token.001": {
    "compact_id": "Ay75d",
    "alias": "E.認証.トークン.001",
    "message": "トークンは{{timestamp}}に期限切れになりました",
    "description": "セッションの有効期限が切れました"
  }
}

// catalog-en.json (translated from ja)
{
  "E.Auth.Token.001": {
    "compact_id": "Ay75d",
    "alias": "E.Auth.Token.001",
    "message": "Token expired at {{timestamp}}",
    "description": "Your session has expired"
  }
}

# Developer adds new diagnostic (primary language)
git add catalogs/catalog-ja.json
git commit -m "feat: add token expiration error"

# English translator (separate commit, no conflicts)
git add catalogs/catalog-en.json
git commit -m "i18n: translate token expiration to English"

# Chinese translator (separate commit, no conflicts)
git add catalogs/catalog-zh.json
git commit -m "i18n: translate token expiration to Chinese"

// Server provides ISO 8601 timestamp
const fields = {
  timestamp: "2024-01-15T10:30:00Z"
};

// Client formats for user's locale
const date = new Date(fields.timestamp);

// English (US)
date.toLocaleString('en-US');
// → "1/15/2024, 10:30:00 AM"

// Japanese
date.toLocaleString('ja-JP');
// → "2024/1/15 10:30:00"

// German
date.toLocaleString('de-DE');
// → "15.1.2024, 10:30:00"

const value = 1234567.89;

// English (US) - comma thousands separator, period decimal
value.toLocaleString('en-US');
// → "1,234,567.89"

// French - space thousands separator, comma decimal
value.toLocaleString('fr-FR');
// → "1 234 567,89"

// Japanese - no thousands separator
value.toLocaleString('ja-JP');
// → "1234567.89"

const amount = 1234.56;

// US Dollars
amount.toLocaleString('en-US', { style: 'currency', currency: 'USD' });
// → "$1,234.56"

// Japanese Yen
amount.toLocaleString('ja-JP', { style: 'currency', currency: 'JPY' });
// → "¥1,235" (no decimals)

// Euro (Germany)
amount.toLocaleString('de-DE', { style: 'currency', currency: 'EUR' });
// → "1.234,56 €"

// Server response
{
  "compact_id": "xY9Kp",
  "fields": {
    "amount": "1234.56",
    "currency": "USD",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

// Client formats
const message = template
  .replace('{{amount}}', formatCurrency(fields.amount, fields.currency, locale))
  .replace('{{timestamp}}', formatDate(fields.timestamp, locale));

Error: E.Auth.Token.001
Token expired at 2024-01-15T10:30:00Z

خطأ: ‪E.مصادقة.‎رمز.‎001‬
انتهت صلاحية الرمز المميز في 2024-01-15T10:30:00Z

שגיאה: ‪E.אימות.‎אסימון.‎001‬
אסימון פג ב-2024-01-15T10:30:00Z

<!-- Arabic -->
<div dir="rtl" lang="ar">
  <p>خطأ: <code dir="ltr">E.مصادقة.رمز.001</code></p>
  <p>انتهت صلاحية الرمز المميز في 2024-01-15T10:30:00Z</p>
</div>

<!-- Hebrew -->
<div dir="rtl" lang="he">
  <p>שגיאה: <code dir="ltr">E.אימות.אסימון.001</code></p>
  <p>אסימון פג ב-2024-01-15T10:30:00Z</p>
</div>

// catalog-ar.json
{
  "wdp_version": "1.0",
  "locale": "ar",
  "namespace": "myapp",
  "diags": {
    "Ay75d": {
      "code": "E.Auth.Token.001",
      "alias": "‪E.مصادقة.‎رمز.‎001‬",  // Arabic alias (severity letter remains LTR)
      "message": "انتهت صلاحية الرمز المميز في {{timestamp}}",
      "description": "انتهت صلاحية جلستك"
    }
  }
}

// catalog-he.json
{
  "wdp_version": "1.0",
  "locale": "he",
  "namespace": "myapp",
  "diags": {
    "Ay75d": {
      "code": "E.Auth.Token.001",
      "alias": "‪E.אימות.‎אסימון.‎001‬",  // Hebrew alias (severity letter remains LTR)
      "message": "אסימון פג ב-{{timestamp}}",
      "description": "הסשן שלך פג תוקף"
    }
  }
}

┌──────────────────────────────────────────────────────────────────────────────┐
│ POSITION (index):                                                            │
│   0    1    2    3    4    5    6    7    8    9   10   11   12  13  14  15  │
├──────────────────────────────────────────────────────────────────────────────┤
│ STORAGE (logical order - what's actually in memory):                         │
│   E    .   645  635  627  62F  642  629   .  631  645  632   .   0   0   1   │
│   ↑    ↑   └────── component ──────┘      ↑  └─ primary ─┘   ↑   └ seq ┘     │
│  LTR   .     (6 Arabic characters)        .  (3 Arabic)      .   (digits)    │
└──────────────────────────────────────────────────────────────────────────────┘

// This parser works for English, Japanese, Arabic, Hebrew - ALL languages
function parseAlias(alias) {
  const parts = alias.split('.');
  return {
    severity: parts[0],   // "E"
    component: parts[1],  // "مصادقة" (Arabic) or "Auth" (English)
    primary: parts[2],    // "رمز" (Arabic) or "Token" (English)
    sequence: parts[3]    // "001"
  };
}

// User requests: zh-TW (Traditional Chinese, Taiwan)
// Fallback chain:
// 1. zh-TW (exact match)
// 2. zh (parent locale)
// 3. en (default/primary)
// 4. compact ID only (Ay75d)

async function loadCatalog(requestedLocale, primaryLocale = 'en') {
  const locales = [
    requestedLocale,           // zh-TW
    requestedLocale.split('-')[0], // zh
    primaryLocale,             // en
  ];
  
  for (const locale of locales) {
    try {
      const catalog = await fetch(`/catalogs/catalog-${locale}.json`);
      if (catalog.ok) return catalog.json();
    } catch (error) {
      continue;
    }
  }
  
  // No catalog available - display compact IDs only
  return null;
}

function getMessage(compactId, locale, primaryLocale = 'en') {
  // Try requested locale (compact ID is the key)
  let entry = catalogs[locale]?.diags[compactId];
  if (entry?.message) return entry.message;
  
  // Fall back to primary locale
  entry = catalogs[primaryLocale]?.diags[compactId];
  if (entry?.message) return entry.message;
  
  // Fall back to compact ID
  return compactId;
}

// Some messages available in user's language, others not
const diagnostics = [
  { code: "E.Auth.Token.001", locale: "ja" },     // Translated
  { code: "E.Payment.Failed.005", locale: "en" }, // Fallback to English
  { code: "E.Unknown.Error.999", locale: null },  // Only compact ID
];

❌ エラー: E.認証.トークン.001
   トークンは2024-01-15T10:30:00Zに期限切れになりました

❌ Error: E.Payment.Failed.005
   Payment processing failed (English fallback)

❌ Error: Ay75d
   (No translation available)

// Detect user's language
const userLocale = navigator.language || 'en';

// Load catalog
async function loadCatalog(locale) {
  try {
    const response = await fetch(`https://cdn.example.com/wdp/v1/catalog-${locale}.json`);
    return response.json();
  } catch (error) {
    console.warn(`Failed to load catalog-${locale}.json:`, error);
    return null;
  }
}

// Initialize
const catalog = await loadCatalog(userLocale);

function expandDiagnostic(compactId, fields, catalog, locale) {
  // Look up entry directly by compact ID (the key)
  const entry = catalog.diags[compactId];
  
  if (!entry) {
    return { code: compactId, message: `Unknown error: ${compactId}` };
  }
  
  // Expand message template
  let message = entry.message;
  for (const [field, value] of Object.entries(fields)) {
    message = message.replace(new RegExp(`\\{\\{${field}\\}\\}`, 'g'), value);
  }
  
  return {
    code: entry.alias,
    compactId: compactId,
    message: message,
    description: entry.description,
    hints: entry.hints
  };
}

// Server does NOT need to know user's language
// Just send canonical code + compact ID + fields

function generateDiagnostic(canonicalCode, fields) {
  const compactId = computeCompactId(canonicalCode);
  
  return {
    [compactId]: {
      f: fields
    }
  };
}

// Usage
app.post('/api/login', (req, res) => {
  if (tokenExpired) {
    res.status(401).json({
      wd: generateDiagnostic('E.Auth.Token.001', {
        timestamp: new Date().toISOString()
      })
    });
  }
});

{
  "wdp_version": "1.0",
  "locale": "en",
  "namespace": "myapp",
  "diags": {
    "Ay75d": {
      "code": "E.Auth.Token.001",
      "alias": "E.Auth.Token.001",
      "message": "Token expired at {{timestamp}}",
      "description": "Your session has expired. Please log in again.",
      "hints": [
        "Click the 'Login' button to sign in",
        "Sessions expire after 30 minutes of inactivity"
      ],
      "docs_url": "https://docs.example.com/errors/auth-token-expired"
    },
    "mN3Yr": {
      "code": "E.Auth.Password.002",
      "alias": "E.Auth.Password.002",
      "message": "Incorrect password ({{attempts}} attempts remaining)",
      "description": "The password you entered is incorrect.",
      "hints": [
        "Check your password for typos",
        "Passwords are case-sensitive",
        "Use 'Forgot Password' to reset"
      ]
    },
    "wN4Qm": {
      "code": "W.Quota.Storage.001",
      "alias": "W.Quota.Storage.001",
      "message": "Storage quota is {{quota_percent}}% full",
      "description": "You are approaching your storage limit.",
      "hints": [
        "Delete unused files to free up space",
        "Upgrade your plan for more storage"
      ]
    }
  }
}

{
  "wdp_version": "1.0",
  "locale": "ja",
  "namespace": "myapp",
  "translated_from": "en",
  "diags": {
    "Ay75d": {
      "code": "E.Auth.Token.001",
      "alias": "E.認証.トークン.001",
      "message": "トークンは{{timestamp}}に期限切れになりました",
      "description": "セッションの有効期限が切れました。もう一度ログインしてください。",
      "hints": [
        "「ログイン」ボタンをクリックしてサインインしてください",
        "セッションは30分間操作がないと期限切れになります"
      ],
      "docs_url": "https://docs.example.com/ja/errors/auth-token-expired"
    },
    "mN3Yr": {
      "code": "E.Auth.Password.002",
      "alias": "E.認証.パスワード.002",
      "message": "パスワードが正しくありません（残り{{attempts}}回）",
      "description": "入力されたパスワードが正しくありません。",
      "hints": [
        "パスワードに入力ミスがないか確認してください",
        "パスワードは大文字と小文字を区別します",
        "「パスワードを忘れた場合」を使用してリセットしてください"
      ]
    },
    "wN4Qm": {
      "code": "W.Quota.Storage.001",
      "alias": "W.割当.ストレージ.001",
      "message": "ストレージ容量が{{quota_percent}}%使用されています",
      "description": "ストレージの上限に近づいています。",
      "hints": [
        "不要なファイルを削除してスペースを確保してください",
        "プランをアップグレードしてストレージを増やすことができます"
      ]
    }
  }
}

{
  "wdp_version": "1.0",
  "locale": "zh",
  "namespace": "myapp",
  "translated_from": "en",
  "diags": {
    "Ay75d": {
      "code": "E.Auth.Token.001",
      "alias": "E.认证.令牌.001",
      "message": "令牌已在{{timestamp}}过期",
      "description": "您的会话已过期。请重新登录。",
      "hints": [
        "点击'登录'按钮进行登录",
        "会话在30分钟无操作后过期"
      ],
      "docs_url": "https://docs.example.com/zh/errors/auth-token-expired"
    },
    "mN3Yr": {
      "code": "E.Auth.Password.002",
      "alias": "E.认证.密码.002",
      "message": "密码不正确（剩余{{attempts}}次尝试）",
      "description": "您输入的密码不正确。",
      "hints": [
        "检查密码是否有拼写错误",
        "密码区分大小写",
        "使用'忘记密码'进行重置"
      ]
    },
    "wN4Qm": {
      "code": "W.Quota.Storage.001",
      "alias": "W.配额.存储.001",
      "message": "存储配额已使用{{quota_percent}}%",
      "description": "您即将达到存储限制。",
      "hints": [
        "删除未使用的文件以释放空间",
        "升级您的计划以获得更多存储空间"
      ]
    }
  }
}

{
  "wdp_version": "1.0",
  "locale": "he",
  "namespace": "myapp",
  "translated_from": "en",
  "diags": {
    "Ay75d": {
      "code": "E.Auth.Token.001",
      "alias": "‪E.אימות.‎אסימון.‎001‬",
      "message": "אסימון פג ב-{{timestamp}}",
      "description": "הסשן שלך פג תוקף. אנא התחבר מחדש.",
      "hints": [
        "לחץ על כפתור 'התחברות' כדי להיכנס",
        "סשנים פגים לאחר 30 דקות של חוסר פעילות"
      ],
      "docs_url": "https://docs.example.com/he/errors/auth-token-expired"
    },
    "mN3Yr": {
      "code": "E.Auth.Password.002",
      "alias": "‪E.אימות.‎סיסמה.‎002‬",
      "message": "סיסמה שגויה (נותרו {{attempts}} ניסיונות)",
      "description": "הסיסמה שהזנת שגויה.",
      "hints": [
        "בדוק שאין שגיאות הקלדה בסיסמה",
        "סיסמאות רגישות לאותיות גדולות וקטנות",
        "השתמש ב'שכחתי סיסמה' לאיפוס"
      ]
    },
    "wN4Qm": {
      "code": "W.Quota.Storage.001",
      "alias": "‪W.מכסה.‎אחסון.‎001‬",
      "message": "מכסת האחסון מלאה ב-{{quota_percent}}%",
      "description": "אתה מתקרב למגבלת האחסון שלך.",
      "hints": [
        "מחק קבצים שאינם בשימוש כדי לפנות מקום",
        "שדרג את התוכנית שלך לקבלת יותר אחסון"
      ]
    }
  }
}

{
  "success": false,
  "wd": {
    "Ay75d": {
      "f": {
        "timestamp": "2024-01-15T10:30:00Z"
      }
    }
  }
}

const catalog = await fetch('/catalogs/catalog-ja.json').then(r => r.json());
const diagnostic = expandDiagnostic('Ay75d', { timestamp: '2024-01-15T10:30:00Z' }, catalog, 'ja');

console.log(diagnostic);
// {
//   code: "E.認証.トークン.001",
//   compactId: "Ay75d",
//   message: "トークンは2024-01-15T10:30:00Zに期限切れになりました",
//   description: "セッションの有効期限が切れました。もう一度ログインしてください。",
//   hints: ["「ログイン」ボタンをクリックしてサインインしてください", ...]
// }

{
  "success": false,
  "error": {
    "code": "E.認証.トークン.001",
    "compact_id": "Ay75d",
    "message": "トークンは2024-01-15T10:30:00Zに期限切れになりました",
    "severity": "E",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}