docs(driver): translate timeout diagnostics readme

Author: lucasgontijopacto

packages/driver/src/cypress/TIMEOUT_DIAGNOSTICS_README.md

@@ -1,18 +1,18 @@
-# Timeout Diagnostics - Smart Error Messages
+# Timeout Diagnostics – Smart Error Messages
 
-## 🎯 Objetivo
+## 🎯 Objective
 
-Melhorar dramaticamente a experiência do desenvolvedor ao lidar com erros de timeout no Cypress, fornecendo **sugestões contextuais e acionáveis** baseadas na análise do contexto do erro.
+Deliver a dramatically better developer experience when Cypress commands time out by providing **contextual, actionable suggestions** derived from the error context.
 
-## 🚀 Motivação
+## 🚀 Motivation
 
-Erros de timeout são extremamente comuns em testes Cypress, mas as mensagens tradicionais são genéricas:
+Timeout errors are extremely common in Cypress tests, yet the built-in messages are typically generic:
 
 ```
 cy.get() timed out waiting 4000ms
 ```
 
-Com este sistema, os desenvolvedores recebem diagnósticos inteligentes:
+With Timeout Diagnostics, developers receive intelligent hints that explain likely causes and quick fixes:
 
 ```
 cy.get() timed out waiting 4000ms
@@ -21,58 +21,58 @@ cy.get() timed out waiting 4000ms
 
 1. The selector appears to target dynamic/loading content
    a) Wait for the loading state to complete: cy.get('.loading-spinner').should('not.exist')
-   b) Consider using data-cy attributes instead of class names that indicate loading states
+   b) Prefer stable data-cy attributes instead of CSS classes that indicate loading states
    c) Use cy.intercept() to wait for the API request that populates this content
    📚 Learn more: https://on.cypress.io/best-practices#Selecting-Elements
 
 2. 8 network requests are still pending
    a) Wait for specific API calls to complete using cy.intercept()
    b) Consider increasing the timeout if the requests are expected to be slow
-   c) Check if some requests are failing or hanging in the Network tab
-   d) Example: cy.intercept("GET", "/api/data").as("getData"); cy.wait("@getData")
+   c) Check the Network tab for requests that are failing or hanging
+   d) Example: cy.intercept('GET', '/api/data').as('getData'); cy.wait('@getData')
    📚 Learn more: https://on.cypress.io/intercept
 ```
 
-## ✨ Funcionalidades
+## ✨ Feature Highlights
 
-### 1. **Detecção de Seletores Problemáticos**
-- Identifica seletores que apontam para conteúdo dinâmico (loading, spinner, skeleton)
-- Detecta seletores complexos e frágeis
-- Alerta sobre IDs dinâmicos (ex: `#user-12345`)
+### 1. **Problematic Selector Detection**
+- Detects selectors that target dynamic content (spinners, skeletons, loading states)
+- Flags complex or fragile selectors
+- Warns when IDs look dynamically generated (e.g., `#user-12345`)
 
-### 2. **Análise de Problemas de Rede**
-- Detecta múltiplas requisições pendentes
-- Identifica timeouts longos que sugerem operações assíncronas
-- Sugere uso de `cy.intercept()` para melhor controle
+### 2. **Network Issue Analysis**
+- Surfaces pending requests
+- Flags unusually long timeouts that suggest async operations still running
+- Promotes `cy.intercept()` and explicit waits for stability
 
-### 3. **Diagnóstico de Animações**
-- Identifica quando animações estão causando delays
-- Sugere configurações para desabilitar animações em testes
+### 3. **Animation Diagnostics**
+- Identifies when animations delay actionability
+- Suggests disabling animations per test or globally
 
-### 4. **Detecção de Mutações Excessivas do DOM**
-- Identifica quando o DOM está mudando rapidamente
-- Sugere esperar por estabilização antes de interagir
+### 4. **DOM Mutation Detection**
+- Spots rapidly changing DOMs
+- Recommends waiting for stability before interacting
 
-### 5. **Sugestões Específicas por Comando**
-- Sugestões customizadas para cada tipo de comando (`get`, `click`, `type`, etc.)
-- Links para documentação relevante
+### 5. **Command-Specific Tips**
+- Tailored suggestions for `cy.get`, `cy.click`, `cy.type`, etc.
+- Links to the relevant Cypress docs for deeper guidance
 
-## 📦 Estrutura
+## 📦 Project Structure
 
 ```
 packages/driver/src/cypress/
-└── timeout_diagnostics.ts       # Lógica principal
+└── timeout_diagnostics.ts       # Core analysis + formatting logic
 
 packages/driver/test/unit/cypress/
-└── timeout_diagnostics.spec.ts  # Testes unitários
+└── timeout_diagnostics.spec.ts  # Unit tests
 ```
 
-## 🔧 API
+## 🔧 API Overview
 
 ```typescript
 import { TimeoutDiagnostics } from './timeout_diagnostics'
 
-// Analisar contexto e obter sugestões
+// Analyze the context and get suggestions
 const suggestions = TimeoutDiagnostics.analyze({
   command: 'get',
   selector: '.loading-spinner',
@@ -81,60 +81,60 @@ const suggestions = TimeoutDiagnostics.analyze({
   animationsRunning: true,
 })
 
-// Formatar sugestões para exibição
+// Format the output for display
 const formatted = TimeoutDiagnostics.formatSuggestions(suggestions)
 
-// Enriquecer mensagem de erro existente
+// Enhance an existing error message with diagnostics
 const enhanced = TimeoutDiagnostics.enhanceTimeoutError(
   'cy.get() timed out',
-  context
+  context,
 )
 ```
 
-## 🎨 Exemplos de Uso
+## 🎨 Usage Examples
 
-### Exemplo 1: Conteúdo Dinâmico
+### Example 1: Dynamic Content
 ```typescript
-// Teste que falha
+// Failing test
 cy.get('.loading-spinner').click()
 
-// Erro melhorado sugere:
-// "Wait for the loading state to complete: 
+// Enhanced error suggests:
+// "Wait for the loading state to complete:
 //  cy.get('.loading-spinner').should('not.exist')"
 ```
 
-### Exemplo 2: Problemas de Rede
+### Example 2: Network Issues
 ```typescript
-// Teste aguardando resposta API
+// Test waiting on API data
 cy.get('.user-data').should('be.visible')
 
-// Erro melhorado sugere:
+// Enhanced error suggests:
 // "Use cy.intercept() to wait for the specific request:
 //  cy.intercept('GET', '/api/users').as('getUsers')
 //  cy.wait('@getUsers')"
 ```
 
-### Exemplo 3: Animações
+### Example 3: Animations
 ```typescript
-// Elemento animando quando clica
+// Element is mid-animation when clicked
 cy.get('.modal-button').click()
 
-// Erro melhorado sugere:
+// Enhanced error suggests:
 // "Disable animations: .click({ waitForAnimations: false })
 //  Or globally: Cypress.config('animationDistanceThreshold', 0)"
 ```
 
-## 🔮 Integração Futura
+## 🔮 Future Integration
 
-Para integrar completamente no Cypress, seria necessário:
+To fully integrate with Cypress core we would need to:
 
-1. **Modificar `error_utils.ts`** para capturar contexto adicional durante timeouts
-2. **Coletar métricas** de rede, DOM e animações durante execução do comando
-3. **Integrar na pipeline de erro** existente do Cypress
-4. **Adicionar configuração** para habilitar/desabilitar diagnósticos
+1. **Extend `error_utils.ts`** to capture richer context when timeouts occur.
+2. **Collect runtime metrics** (network, DOM mutations, animations) alongside each command.
+3. **Pipe diagnostics into the existing error formatter** so suggestions appear automatically.
+4. **Add configuration flags** so users can opt in/out or tweak verbosity.
 
 ```typescript
-// Exemplo de integração em error_utils.ts
+// Sketch for error_utils.ts
 import TimeoutDiagnostics from './timeout_diagnostics'
 
 const createTimeoutError = (cmd, ms) => {
@@ -146,53 +146,52 @@ const createTimeoutError = (cmd, ms) => {
     animationsRunning: hasRunningAnimations(),
     domMutations: getDOMMutationCount(),
   }
-  
+
   const baseMessage = `cy.${cmd.get('name')}() timed out waiting ${ms}ms`
   return TimeoutDiagnostics.enhanceTimeoutError(baseMessage, context)
 }
 ```
 
-## 📊 Benefícios
+## 📊 Benefits
 
-1. **Reduz tempo de debugging**: Desenvolvedores identificam problemas mais rapidamente
-2. **Educação inline**: Ensina melhores práticas durante o desenvolvimento
-3. **Menos frustração**: Erros mais claros = desenvolvedores mais felizes
-4. **Reduz issues no GitHub**: Menos perguntas sobre "por que meu teste timeout?"
-5. **Melhora adoção**: Desenvolvedores iniciantes aprendem mais rápido
+1. **Faster debugging** – developers quickly learn which condition to address.
+2. **Inline education** – suggests Cypress best practices in the moment.
+3. **Lower frustration** – clearer errors mean happier engineers.
+4. **Fewer GitHub issues** – reduces "why is my test timing out?" questions.
+5. **Easier onboarding** – newer users learn patterns through the suggestions.
 
-## 🧪 Testes
+## 🧪 Tests
 
-Execute os testes unitários:
+Run the unit suite:
 
 ```bash
 cd packages/driver
 yarn test timeout_diagnostics.spec.ts
 ```
 
-Cobertura inclui:
-- ✅ Detecção de todos os tipos de problemas
-- ✅ Formatação de mensagens
-- ✅ Casos extremos e edge cases
-- ✅ Combinação de múltiplos diagnósticos
+Coverage includes:
+- ✅ Selector, network, animation, and DOM mutation detection
+- ✅ Message formatting
+- ✅ Edge cases and combined diagnostics
 
-## 🚀 Próximos Passos
+## 🚀 Next Steps
 
-1. ✅ Criar módulo de diagnósticos com testes
-2. ⏳ Integrar com sistema de erros existente
-3. ⏳ Adicionar coleta de métricas de contexto
-4. ⏳ Criar configuração para habilitar/desabilitar
-5. ⏳ Adicionar mais padrões e sugestões baseado em feedback
-6. ⏳ Documentação para usuários finais
+1. ✅ Build the diagnostics module with tests
+2. ⏳ Wire it into the existing error system
+3. ⏳ Capture contextual metrics during command execution
+4. ⏳ Provide configuration toggles for diagnostics
+5. ⏳ Expand heuristics based on user feedback
+6. ⏳ Document the feature for end users
 
-## 🤝 Contribuindo
+## 🤝 Contributing
 
-Este é um sistema extensível. Para adicionar novos diagnósticos:
+Timeout Diagnostics is intentionally extensible. To add new heuristics:
 
-1. Adicione padrão em `COMMON_PATTERNS`
-2. Crie método `analyze*Issues()`
-3. Adicione testes correspondentes
-4. Documente o novo diagnóstico
+1. Add a pattern to `COMMON_PATTERNS`.
+2. Implement a corresponding `analyze*Issues()` helper.
+3. Cover it with unit tests.
+4. Document the behavior in this README.
 
-## 📝 Licença
+## 📝 License
 
-MIT - Consistente com o projeto Cypress
+MIT — consistent with the Cypress project.