feat(translation-agent): enhance translation agent commit diff

[m-dilorenzi]

This PR introduces significant enhancements to the Translation Sync Agent system. The changes implement intelligent commit history tracking, primary language detection, robust API retry logic, and comprehensive technical documentation.

The workflow now automatically synchronizes translations between English and Italian documentation while respecting developer intent and preventing redundant re-processing of already-translated commits.

Changes Overview

Commit Processing & Language Detection

Enhanced the workflow to implement a sophisticated analysis system:

• Smart History Tracking: Queries GitHub API to find the last successful workflow execution, ensuring commits are processed only once. Uses merge base to identify PR start point.

• Primary Language Detection: Analyzes PR commits sequentially to determine if changes are primarily English or Italian. Supports exclusive language detection, majority voting for mixed commits, and gracefully skips ambiguous PRs.

• File-by-File Translation Logic: Each modified file is analyzed for language match with PR primary language, manual translation indicators (both counterparts in same commit), and automatic translation needs.

• Workflow Bot Filtering: Prevents infinite loops by skipping commits with "auto-sync translations" message, ensuring the system doesn't re-process its own changes.

API Retry Management

Implemented robust retry logic for API calls to handle transient failures:

• Exponential Backoff: Maximum 5 retry attempts with configurable delays. Base delay starts at 2 seconds and doubles with each attempt (2^attempt_number).

• Rate Limit Handling: Respects Retry-After headers from GitHub Models API and implements sophisticated timeout handling with 60-second request timeout.

• Graceful Degradation: Clear error messages logged at each retry stage, allowing the workflow to continue processing remaining files even if individual API calls fail.

Enhanced AI Prompt System

Refined the AI translation system with dual-persona approach:

• Translation Agent: Expert technical documentation translator with temperature 0.2 for consistent, reproducible translations.

• Positioning Agent: Expert documentation editor with temperature 0 for deterministic content placement in target files.

Both agents follow critical formatting rules ensuring markdown structure preservation, proper handling of section IDs, links, and technical terminology consistency.

Comprehensive Technical Documentation

Significantly expanded documentation for better understanding and maintenance:

• README.md
  Detailed "How It Works" section explaining all 5 execution phases, best practices, and 5 comprehensive scenarios covering pure English PR, pure Italian PR, manual translation, mixed language PR, and re-triggered workflow handling. Includes real usage examples and table showing when auto-translation is skipped.

• ARCHITECTURE.md
  New "Commit History and Processing" section documenting history analysis system, primary language detection algorithm, and commit filtering logic. Enhanced workflow execution flow diagram, detailed Git operations explaining merge base and commit range calculations, improved AI integration specifics with temperature settings and rate limiting details, expanded monitoring section with real workflow log examples, and comprehensive system limitations with 11 detailed points.

Technical Highlights

The workflow now follows this optimized flow:

1. Commit History Analysis - identifies commits to process using GitHub API
2. Primary Language Detection - determines PR language direction
3. File Analysis - checks translation needs file-by-file
4. API Testing - fail-fast validation of GitHub Models access
5. Translation Processing - generates and positions translations
6. Commit & Push - atomic operation with all translations

Key improvements include avoiding re-processing already translated commits, consistent translation direction based on PR language, respect for manual translations when both files are modified together, and graceful handling of API rate limiting and timeouts.