I18n Translation Validator

{
  "hookConfig": {
    "hooks": {
      "postToolUse": {
        "script": "./.claude/hooks/i18n-translation-validator.sh",
        "matchers": [
          "write",
          "edit"
        ]
      }
    }
  },
  "scriptContent": "#!/usr/bin/env bash\n\n# Read the tool input from stdin\nINPUT=$(cat)\nTOOL_NAME=$(echo \"$INPUT\" | jq -r '.tool_name')\nFILE_PATH=$(echo \"$INPUT\" | jq -r '.tool_input.file_path // .tool_input.path // \"\"')\n\nif [ -z \"$FILE_PATH\" ]; then\n  exit 0\nfi\n\n# Check if this is a translation/localization file\nif [[ \"$FILE_PATH\" == *locales/*.json ]] || [[ \"$FILE_PATH\" == *i18n/*.json ]] || [[ \"$FILE_PATH\" == *lang/*.json ]] || [[ \"$FILE_PATH\" == *translations/*.json ]] || [[ \"$FILE_PATH\" == *.po ]] || [[ \"$FILE_PATH\" == *messages/*.properties ]]; then\n  echo \"🌍 i18n Translation Validation for: $(basename \"$FILE_PATH\")\" >&2\n  \n  # Initialize validation counters\n  ERRORS=0\n  WARNINGS=0\n  MISSING_KEYS=0\n  ORPHANED_KEYS=0\n  TOTAL_KEYS=0\n  \n  # Function to report validation results\n  report_validation() {\n    local level=\"$1\"\n    local message=\"$2\"\n    \n    case \"$level\" in\n      \"ERROR\")\n        echo \"❌ ERROR: $message\" >&2\n        ERRORS=$((ERRORS + 1))\n        ;;\n      \"WARNING\")\n        echo \"⚠️ WARNING: $message\" >&2\n        WARNINGS=$((WARNINGS + 1))\n        ;;\n      \"MISSING\")\n        echo \"🔍 MISSING: $message\" >&2\n        MISSING_KEYS=$((MISSING_KEYS + 1))\n        ;;\n      \"ORPHANED\")\n        echo \"🏷️ ORPHANED: $message\" >&2\n        ORPHANED_KEYS=$((ORPHANED_KEYS + 1))\n        ;;\n      \"PASS\")\n        echo \"✅ PASS: $message\" >&2\n        ;;\n      \"INFO\")\n        echo \"ℹ️ INFO: $message\" >&2\n        ;;\n    esac\n  }\n  \n  # Check if file exists and is readable\n  if [ ! -f \"$FILE_PATH\" ]; then\n    report_validation \"ERROR\" \"Translation file not found: $FILE_PATH\"\n    exit 1\n  fi\n  \n  if [ ! -r \"$FILE_PATH\" ]; then\n    report_validation \"ERROR\" \"Translation file is not readable: $FILE_PATH\"\n    exit 1\n  fi\n  \n  # Determine file format\n  FILE_EXT=\"${FILE_PATH##*.}\"\n  LOCALE_DIR=\"$(dirname \"$FILE_PATH\")\"\n  FILE_NAME=\"$(basename \"$FILE_PATH\")\"\n  LOCALE_CODE=\"${FILE_NAME%.*}\"\n  \n  echo \"📊 Translation file: $FILE_NAME (format: $FILE_EXT, locale: $LOCALE_CODE)\" >&2\n  \n  # 1. File Format Validation\n  echo \"📋 Validating file format...\" >&2\n  \n  case \"$FILE_EXT\" in\n    \"json\")\n      if jq empty \"$FILE_PATH\" 2>/dev/null; then\n        report_validation \"PASS\" \"Valid JSON syntax\"\n        TOTAL_KEYS=$(jq -r 'keys | length' \"$FILE_PATH\" 2>/dev/null || echo \"0\")\n      else\n        report_validation \"ERROR\" \"Invalid JSON syntax - file cannot be parsed\"\n        exit 1\n      fi\n      ;;\n    \"po\")\n      if command -v msgfmt &> /dev/null; then\n        if msgfmt --check \"$FILE_PATH\" -o /dev/null 2>/dev/null; then\n          report_validation \"PASS\" \"Valid PO file format\"\n        else\n          report_validation \"ERROR\" \"Invalid PO file format\"\n        fi\n      else\n        report_validation \"WARNING\" \"msgfmt not available - limited PO validation\"\n      fi\n      ;;\n    \"properties\")\n      # Basic properties file validation\n      if grep -q '=' \"$FILE_PATH\" 2>/dev/null; then\n        report_validation \"PASS\" \"Properties file format detected\"\n      else\n        report_validation \"WARNING\" \"No key=value pairs found in properties file\"\n      fi\n      ;;\n    *)\n      report_validation \"WARNING\" \"Unknown translation file format: $FILE_EXT\"\n      ;;\n  esac\n  \n  # 2. Find Base Translation File (for comparison)\n  echo \"🔍 Locating base translation file...\" >&2\n  \n  BASE_FILE=\"\"\n  BASE_CANDIDATES=(\"en.json\" \"en-US.json\" \"en_US.json\" \"base.json\" \"default.json\")\n  \n  for candidate in \"${BASE_CANDIDATES[@]}\"; do\n    if [ -f \"$LOCALE_DIR/$candidate\" ] && [ \"$LOCALE_DIR/$candidate\" != \"$FILE_PATH\" ]; then\n      BASE_FILE=\"$LOCALE_DIR/$candidate\"\n      echo \"   📁 Base file found: $candidate\" >&2\n      break\n    fi\n  done\n  \n  if [ -z \"$BASE_FILE\" ]; then\n    # Look for any .json file in the directory as base\n    FIRST_JSON=$(find \"$LOCALE_DIR\" -name '*.json' -not -path \"$FILE_PATH\" | head -1)\n    if [ -n \"$FIRST_JSON\" ]; then\n      BASE_FILE=\"$FIRST_JSON\"\n      echo \"   📁 Using first available JSON as base: $(basename \"$BASE_FILE\")\" >&2\n    else\n      echo \"   ⚠️ No base translation file found - running standalone validation\" >&2\n    fi\n  fi\n  \n  # 3. Key Structure Validation (JSON files)\n  if [ \"$FILE_EXT\" = \"json\" ]; then\n    echo \"🔑 Analyzing translation keys...\" >&2\n    \n    # Check for nested vs flat structure\n    NESTED_COUNT=$(jq '[.. | objects | keys] | flatten | length' \"$FILE_PATH\" 2>/dev/null || echo \"0\")\n    if [ \"$NESTED_COUNT\" -gt \"$TOTAL_KEYS\" ]; then\n      echo \"   📊 Nested key structure detected ($NESTED_COUNT total keys)\" >&2\n    else\n      echo \"   📊 Flat key structure ($TOTAL_KEYS keys)\" >&2\n    fi\n    \n    # Check for empty values\n    EMPTY_VALUES=$(jq '[.. | select(type == \"string\" and length == 0)] | length' \"$FILE_PATH\" 2>/dev/null || echo \"0\")\n    if [ \"$EMPTY_VALUES\" -gt 0 ]; then\n      report_validation \"WARNING\" \"$EMPTY_VALUES empty translation values found\"\n    fi\n    \n    # Check for untranslated strings (same as key)\n    UNTRANSLATED=0\n    if command -v jq &> /dev/null; then\n      UNTRANSLATED=$(jq -r 'to_entries[] | select(.key == .value) | .key' \"$FILE_PATH\" 2>/dev/null | wc -l | xargs || echo \"0\")\n      if [ \"$UNTRANSLATED\" -gt 0 ]; then\n        report_validation \"WARNING\" \"$UNTRANSLATED potentially untranslated strings (key equals value)\"\n      fi\n    fi\n  fi\n  \n  # 4. Compare with Base File (if available)\n  if [ -n \"$BASE_FILE\" ] && [ -f \"$BASE_FILE\" ]; then\n    echo \"🔄 Comparing with base translation file...\" >&2\n    \n    if [ \"$FILE_EXT\" = \"json\" ]; then\n      # Extract all keys from both files\n      BASE_KEYS_FILE=\"/tmp/base_keys_$$\"\n      CURRENT_KEYS_FILE=\"/tmp/current_keys_$$\"\n      \n      # Get all nested keys (dot notation)\n      jq -r 'paths(scalars) as $p | $p | join(\".\")' \"$BASE_FILE\" 2>/dev/null | sort > \"$BASE_KEYS_FILE\"\n      jq -r 'paths(scalars) as $p | $p | join(\".\")' \"$FILE_PATH\" 2>/dev/null | sort > \"$CURRENT_KEYS_FILE\"\n      \n      # Find missing keys (in base but not in current)\n      MISSING_KEYS_LIST=\"/tmp/missing_keys_$$\"\n      comm -23 \"$BASE_KEYS_FILE\" \"$CURRENT_KEYS_FILE\" > \"$MISSING_KEYS_LIST\"\n      MISSING_COUNT=$(wc -l < \"$MISSING_KEYS_LIST\" | xargs)\n      \n      if [ \"$MISSING_COUNT\" -gt 0 ]; then\n        report_validation \"MISSING\" \"$MISSING_COUNT translation keys missing from base\"\n        echo \"   Missing keys:\" >&2\n        head -10 \"$MISSING_KEYS_LIST\" | while read key; do\n          echo \"     - $key\" >&2\n        done\n        [ \"$MISSING_COUNT\" -gt 10 ] && echo \"     ... and $((MISSING_COUNT - 10)) more\" >&2\n      else\n        report_validation \"PASS\" \"All base translation keys are present\"\n      fi\n      \n      # Find orphaned keys (in current but not in base)\n      ORPHANED_KEYS_LIST=\"/tmp/orphaned_keys_$$\"\n      comm -13 \"$BASE_KEYS_FILE\" \"$CURRENT_KEYS_FILE\" > \"$ORPHANED_KEYS_LIST\"\n      ORPHANED_COUNT=$(wc -l < \"$ORPHANED_KEYS_LIST\" | xargs)\n      \n      if [ \"$ORPHANED_COUNT\" -gt 0 ]; then\n        report_validation \"ORPHANED\" \"$ORPHANED_COUNT keys not found in base (potential orphans)\"\n        echo \"   Orphaned keys:\" >&2\n        head -5 \"$ORPHANED_KEYS_LIST\" | while read key; do\n          echo \"     - $key\" >&2\n        done\n        [ \"$ORPHANED_COUNT\" -gt 5 ] && echo \"     ... and $((ORPHANED_COUNT - 5)) more\" >&2\n      else\n        report_validation \"PASS\" \"No orphaned keys detected\"\n      fi\n      \n      # Calculate completeness percentage\n      BASE_KEY_COUNT=$(wc -l < \"$BASE_KEYS_FILE\" | xargs)\n      if [ \"$BASE_KEY_COUNT\" -gt 0 ]; then\n        TRANSLATED_COUNT=$((BASE_KEY_COUNT - MISSING_COUNT))\n        COMPLETENESS=$((TRANSLATED_COUNT * 100 / BASE_KEY_COUNT))\n        echo \"   📊 Translation completeness: $COMPLETENESS% ($TRANSLATED_COUNT/$BASE_KEY_COUNT)\" >&2\n        \n        if [ \"$COMPLETENESS\" -eq 100 ]; then\n          report_validation \"PASS\" \"Translation is 100% complete\"\n        elif [ \"$COMPLETENESS\" -ge 90 ]; then\n          report_validation \"WARNING\" \"Translation is $COMPLETENESS% complete (good but not perfect)\"\n        elif [ \"$COMPLETENESS\" -ge 70 ]; then\n          report_validation \"WARNING\" \"Translation is $COMPLETENESS% complete (needs attention)\"\n        else\n          report_validation \"ERROR\" \"Translation is only $COMPLETENESS% complete (significant gaps)\"\n        fi\n      fi\n      \n      # Cleanup temp files\n      rm -f \"$BASE_KEYS_FILE\" \"$CURRENT_KEYS_FILE\" \"$MISSING_KEYS_LIST\" \"$ORPHANED_KEYS_LIST\"\n    fi\n  fi\n  \n  # 5. Variable Placeholder Validation\n  echo \"🔤 Checking variable placeholders...\" >&2\n  \n  if [ \"$FILE_EXT\" = \"json\" ]; then\n    # Check for common placeholder patterns\n    PLACEHOLDER_PATTERNS=(\n      '{{[^}]+}}'     # Handlebars: {{variable}}\n      '{[^}]+}'       # Simple: {variable}\n      '%[a-zA-Z_]+%'  # Percent: %variable%\n      '\\$\\{[^}]+\\}'   # Dollar: ${variable}\n      '%[sd]'         # Printf style: %s, %d\n    )\n    \n    PLACEHOLDER_COUNT=0\n    for pattern in \"${PLACEHOLDER_PATTERNS[@]}\"; do\n      COUNT=$(grep -oE \"$pattern\" \"$FILE_PATH\" 2>/dev/null | wc -l | xargs || echo \"0\")\n      PLACEHOLDER_COUNT=$((PLACEHOLDER_COUNT + COUNT))\n    done\n    \n    if [ \"$PLACEHOLDER_COUNT\" -gt 0 ]; then\n      echo \"   📝 $PLACEHOLDER_COUNT variable placeholders found\" >&2\n      \n      # Check for unmatched placeholders if base file exists\n      if [ -n \"$BASE_FILE\" ]; then\n        # This is a simplified check - in practice, you'd want more sophisticated matching\n        echo \"   🔍 Cross-referencing placeholders with base file...\" >&2\n      fi\n    else\n      echo \"   ℹ️ No variable placeholders detected\" >&2\n    fi\n  fi\n  \n  # 6. Locale-Specific Validation\n  echo \"🌐 Locale-specific validation...\" >&2\n  \n  case \"$LOCALE_CODE\" in\n    \"ar\"*|\"he\"*|\"fa\"*)\n      echo \"   🔄 RTL language detected - ensure proper text direction handling\" >&2\n      ;;\n    \"zh\"*|\"ja\"*|\"ko\"*)\n      echo \"   🈴 CJK language detected - ensure proper character encoding\" >&2\n      ;;\n    \"en\"*)\n      echo \"   🇺🇸 English locale - checking for common issues\" >&2\n      ;;\n    *)\n      echo \"   🌍 Locale: $LOCALE_CODE\" >&2\n      ;;\n  esac\n  \n  # Check for potential encoding issues (non-ASCII characters)\n  if [ \"$FILE_EXT\" = \"json\" ]; then\n    NON_ASCII_COUNT=$(grep -P '[^\\x00-\\x7F]' \"$FILE_PATH\" 2>/dev/null | wc -l | xargs || echo \"0\")\n    if [ \"$NON_ASCII_COUNT\" -gt 0 ]; then\n      echo \"   🔤 $NON_ASCII_COUNT lines contain non-ASCII characters (normal for international content)\" >&2\n    fi\n  fi\n  \n  # 7. Multi-file Consistency Check\n  echo \"📁 Checking consistency across locale files...\" >&2\n  \n  LOCALE_FILES=()\n  while IFS= read -r -d '' file; do\n    LOCALE_FILES+=(\"$file\")\n  done < <(find \"$LOCALE_DIR\" -name \"*.$FILE_EXT\" -print0 2>/dev/null)\n  \n  LOCALE_COUNT=${#LOCALE_FILES[@]}\n  if [ \"$LOCALE_COUNT\" -gt 1 ]; then\n    echo \"   📊 Found $LOCALE_COUNT locale files in directory\" >&2\n    \n    # Check if all files have similar key counts (within 20% difference)\n    if [ \"$FILE_EXT\" = \"json\" ] && [ \"$TOTAL_KEYS\" -gt 0 ]; then\n      INCONSISTENT_FILES=0\n      for locale_file in \"${LOCALE_FILES[@]}\"; do\n        if [ \"$locale_file\" != \"$FILE_PATH\" ]; then\n          OTHER_KEY_COUNT=$(jq -r 'keys | length' \"$locale_file\" 2>/dev/null || echo \"0\")\n          DIFF_PERCENT=$((abs(TOTAL_KEYS - OTHER_KEY_COUNT) * 100 / TOTAL_KEYS))\n          \n          if [ \"$DIFF_PERCENT\" -gt 20 ]; then\n            INCONSISTENT_FILES=$((INCONSISTENT_FILES + 1))\n          fi\n        fi\n      done\n      \n      if [ \"$INCONSISTENT_FILES\" -gt 0 ]; then\n        report_validation \"WARNING\" \"$INCONSISTENT_FILES locale files have significantly different key counts\"\n      else\n        report_validation \"PASS\" \"All locale files have consistent key counts\"\n      fi\n    fi\n  else\n    echo \"   ℹ️ Single locale file found\" >&2\n  fi\n  \n  # 8. Generate Validation Summary\n  echo \"\" >&2\n  echo \"📋 i18n Translation Validation Summary:\" >&2\n  echo \"=====================================\" >&2\n  echo \"   📄 File: $FILE_NAME\" >&2\n  echo \"   🌍 Locale: $LOCALE_CODE\" >&2\n  echo \"   📊 Format: $FILE_EXT\" >&2\n  [ \"$TOTAL_KEYS\" -gt 0 ] && echo \"   🔑 Total Keys: $TOTAL_KEYS\" >&2\n  echo \"   ❌ Errors: $ERRORS\" >&2\n  echo \"   ⚠️ Warnings: $WARNINGS\" >&2\n  echo \"   🔍 Missing Keys: $MISSING_KEYS\" >&2\n  echo \"   🏷️ Orphaned Keys: $ORPHANED_KEYS\" >&2\n  \n  if [ \"$ERRORS\" -eq 0 ] && [ \"$MISSING_KEYS\" -eq 0 ]; then\n    if [ \"$WARNINGS\" -eq 0 ] && [ \"$ORPHANED_KEYS\" -eq 0 ]; then\n      echo \"   🎉 Status: EXCELLENT - Translation file is complete and consistent\" >&2\n    else\n      echo \"   ✅ Status: GOOD - Translation is functional with minor issues\" >&2\n    fi\n  elif [ \"$ERRORS\" -eq 0 ]; then\n    echo \"   ⚠️ Status: INCOMPLETE - Missing translations need attention\" >&2\n  else\n    echo \"   ❌ Status: ERRORS - Critical issues must be fixed\" >&2\n  fi\n  \n  echo \"\" >&2\n  echo \"💡 i18n Translation Best Practices:\" >&2\n  echo \"   • Keep translation keys consistent across all locales\" >&2\n  echo \"   • Use meaningful, hierarchical key names\" >&2\n  echo \"   • Validate placeholder variables across languages\" >&2\n  echo \"   • Consider cultural context in translations\" >&2\n  echo \"   • Test with longer/shorter text in different languages\" >&2\n  echo \"   • Use proper character encoding (UTF-8)\" >&2\n  \n  # Exit with error if there are critical issues\n  if [ \"$ERRORS\" -gt 0 ]; then\n    echo \"⚠️ Translation validation completed with errors\" >&2\n    exit 1\n  fi\n  \nelse\n  # Not a translation file, exit silently\n  exit 0\nfi\n\nexit 0"
}