Web-Dev-For-Beginners/translations/br/AGENTS.md

<!--
CO_OP_TRANSLATOR_METADATA:
{
  "original_hash": "a362efd06d64d4134a0cfe8515a86d34",
  "translation_date": "2025-10-03T11:25:01+00:00",
  "source_file": "AGENTS.md",
  "language_code": "br"
}
-->
# AGENTS.md

## Visão Geral do Projeto

Este é um repositório de currículo educacional para ensinar fundamentos de desenvolvimento web a iniciantes. O currículo é um curso abrangente de 12 semanas desenvolvido pelos Microsoft Cloud Advocates, com 24 aulas práticas que abordam JavaScript, CSS e HTML.

### Componentes Principais

- **Conteúdo Educacional**: 24 aulas estruturadas organizadas em módulos baseados em projetos
- **Projetos Práticos**: Terrário, Jogo de Digitação, Extensão de Navegador, Jogo Espacial, Aplicativo Bancário, Editor de Código e Assistente de Chat com IA
- **Quizzes Interativos**: 48 quizzes com 3 perguntas cada (avaliações pré/pós-aula)
- **Suporte Multilíngue**: Traduções automáticas para mais de 50 idiomas via GitHub Actions
- **Tecnologias**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (para projetos de IA)

### Arquitetura

- Repositório educacional com estrutura baseada em aulas
- Cada pasta de aula contém README, exemplos de código e soluções
- Projetos independentes em diretórios separados (quiz-app, vários projetos de aula)
- Sistema de tradução usando GitHub Actions (co-op-translator)
- Documentação servida via Docsify e disponível em PDF

## Comandos de Configuração

Este repositório é principalmente para consumo de conteúdo educacional. Para trabalhar com projetos específicos:

### Configuração do Repositório Principal

```bash
git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
cd Web-Dev-For-Beginners
```

### Configuração do Quiz App (Vue 3 + Vite)

```bash
cd quiz-app
npm install
npm run dev        # Start development server
npm run build      # Build for production
npm run lint       # Run ESLint
```

### API do Projeto Bancário (Node.js + Express)

```bash
cd 7-bank-project/api
npm install
npm start          # Start API server
npm run lint       # Run ESLint
npm run format     # Format with Prettier
```

### Projetos de Extensão de Navegador

```bash
cd 5-browser-extension/solution
npm install
# Follow browser-specific extension loading instructions
```

### Projetos de Jogo Espacial

```bash
cd 6-space-game/solution
npm install
# Open index.html in browser or use Live Server
```

### Projeto de Chat (Backend em Python)

```bash
cd 9-chat-project/solution/backend/python
pip install openai
# Set GITHUB_TOKEN environment variable
python api.py
```

## Fluxo de Trabalho de Desenvolvimento

### Para Contribuidores de Conteúdo

1. **Faça um fork do repositório** na sua conta do GitHub
2. **Clone o fork** localmente
3. **Crie uma nova branch** para suas alterações
4. Faça alterações no conteúdo das aulas ou nos exemplos de código
5. Teste quaisquer alterações de código nos diretórios de projetos relevantes
6. Envie pull requests seguindo as diretrizes de contribuição

### Para Estudantes

1. Faça um fork ou clone do repositório
2. Navegue pelos diretórios das aulas sequencialmente
3. Leia os arquivos README de cada aula
4. Complete os quizzes pré-aula em https://ff-quizzes.netlify.app/web/
5. Trabalhe nos exemplos de código nas pastas das aulas
6. Complete os exercícios e desafios
7. Faça os quizzes pós-aula

### Desenvolvimento ao Vivo

- **Documentação**: Execute `docsify serve` na raiz (porta 3000)
- **Quiz App**: Execute `npm run dev` no diretório quiz-app
- **Projetos**: Use a extensão Live Server do VS Code para projetos HTML
- **Projetos de API**: Execute `npm start` nos diretórios de API correspondentes

## Instruções de Teste

### Teste do Quiz App

```bash
cd quiz-app
npm run lint       # Check for code style issues
npm run build      # Verify build succeeds
```

### Teste da API Bancária

```bash
cd 7-bank-project/api
npm run lint       # Check for code style issues
node server.js     # Verify server starts without errors
```

### Abordagem Geral de Teste

- Este é um repositório educacional sem testes automatizados abrangentes
- O teste manual foca em:
  - Exemplos de código executando sem erros
  - Links na documentação funcionando corretamente
  - Builds dos projetos concluindo com sucesso
  - Exemplos seguindo boas práticas

### Verificações Antes de Submissão

- Execute `npm run lint` nos diretórios com package.json
- Verifique se os links em markdown são válidos
- Teste os exemplos de código no navegador ou Node.js
- Certifique-se de que as traduções mantêm a estrutura adequada

## Diretrizes de Estilo de Código

### JavaScript

- Use sintaxe moderna ES6+
- Siga as configurações padrão do ESLint fornecidas nos projetos
- Use nomes de variáveis e funções significativos para clareza educacional
- Adicione comentários explicando conceitos para os alunos
- Formate usando Prettier onde configurado

### HTML/CSS

- Elementos semânticos do HTML5
- Princípios de design responsivo
- Convenções claras de nomenclatura de classes
- Comentários explicando técnicas de CSS para os alunos

### Python

- Diretrizes de estilo PEP 8
- Exemplos de código claros e educacionais
- Dicas de tipo onde úteis para aprendizado

### Documentação em Markdown

- Hierarquia clara de títulos
- Blocos de código com especificação de linguagem
- Links para recursos adicionais
- Capturas de tela e imagens em diretórios `images/`
- Texto alternativo para imagens para acessibilidade

### Organização de Arquivos

- Aulas numeradas sequencialmente (1-getting-started-lessons, 2-js-basics, etc.)
- Cada projeto tem diretórios `solution/` e frequentemente `start/` ou `your-work/`
- Imagens armazenadas em pastas `images/` específicas de cada aula
- Traduções na estrutura `translations/{language-code}/`

## Build e Implantação

### Implantação do Quiz App (Azure Static Web Apps)

O quiz-app está configurado para implantação no Azure Static Web Apps:

```bash
cd quiz-app
npm run build      # Creates dist/ folder
# Deploys via GitHub Actions workflow on push to main
```

Configuração do Azure Static Web Apps:
- **Localização do aplicativo**: `/quiz-app`
- **Localização de saída**: `dist`
- **Workflow**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`

### Geração de PDF da Documentação

```bash
npm install                    # Install docsify-to-pdf
npm run convert               # Generate PDF from docs
```

### Documentação Docsify

```bash
npm install -g docsify-cli    # Install Docsify globally
docsify serve                 # Serve on localhost:3000
```

### Builds Específicos de Projetos

Cada diretório de projeto pode ter seu próprio processo de build:
- Projetos Vue: `npm run build` cria pacotes de produção
- Projetos estáticos: Sem etapa de build, sirva os arquivos diretamente

## Diretrizes para Pull Requests

### Formato do Título

Use títulos claros e descritivos indicando a área de alteração:
- `[Quiz-app] Adicionar novo quiz para aula X`
- `[Lesson-3] Corrigir erro de digitação no projeto terrário`
- `[Translation] Adicionar tradução para espanhol na aula 5`
- `[Docs] Atualizar instruções de configuração`

### Verificações Necessárias

Antes de enviar um PR:

1. **Qualidade do Código**:
   - Execute `npm run lint` nos diretórios de projeto afetados
   - Corrija todos os erros e avisos de lint

2. **Verificação de Build**:
   - Execute `npm run build` se aplicável
   - Certifique-se de que não há erros de build

3. **Validação de Links**:
   - Teste todos os links em markdown
   - Verifique se as referências de imagens funcionam

4. **Revisão de Conteúdo**:
   - Revise para corrigir erros de ortografia e gramática
   - Certifique-se de que os exemplos de código estão corretos e educacionais
   - Verifique se as traduções mantêm o significado original

### Requisitos de Contribuição

- Concorde com o Microsoft CLA (verificação automatizada no primeiro PR)
- Siga o [Código de Conduta de Código Aberto da Microsoft](https://opensource.microsoft.com/codeofconduct/)
- Consulte [CONTRIBUTING.md](./CONTRIBUTING.md) para diretrizes detalhadas
- Referencie números de issues na descrição do PR, se aplicável

### Processo de Revisão

- PRs revisados por mantenedores e pela comunidade
- Clareza educacional é priorizada
- Exemplos de código devem seguir as melhores práticas atuais
- Traduções revisadas para precisão e adequação cultural

## Sistema de Tradução

### Tradução Automática

- Usa GitHub Actions com workflow co-op-translator
- Traduções automáticas para mais de 50 idiomas
- Arquivos fonte nos diretórios principais
- Arquivos traduzidos em diretórios `translations/{language-code}/`

### Adicionando Melhorias Manuais à Tradução

1. Localize o arquivo em `translations/{language-code}/`
2. Faça melhorias preservando a estrutura
3. Certifique-se de que os exemplos de código permanecem funcionais
4. Teste qualquer conteúdo de quiz localizado

### Metadados de Tradução

Arquivos traduzidos incluem cabeçalho de metadados:
```markdown
<!--
CO_OP_TRANSLATOR_METADATA:
{
  "original_hash": "...",
  "translation_date": "...",
  "source_file": "...",
  "language_code": "..."
}
-->
```

## Depuração e Solução de Problemas

### Problemas Comuns

**Quiz app não inicia**:
- Verifique a versão do Node.js (recomendado v14+)
- Exclua `node_modules` e `package-lock.json`, execute `npm install` novamente
- Verifique conflitos de porta (padrão: Vite usa porta 5173)

**Servidor de API não inicia**:
- Verifique se a versão do Node.js atende ao mínimo (node >=10)
- Verifique se a porta já está em uso
- Certifique-se de que todas as dependências estão instaladas com `npm install`

**Extensão de navegador não carrega**:
- Verifique se o manifest.json está formatado corretamente
- Verifique o console do navegador para erros
- Siga as instruções específicas do navegador para instalação de extensões

**Problemas no projeto de chat em Python**:
- Certifique-se de que o pacote OpenAI está instalado: `pip install openai`
- Verifique se a variável de ambiente GITHUB_TOKEN está configurada
- Verifique as permissões de acesso aos modelos do GitHub

**Docsify não serve os documentos**:
- Instale docsify-cli globalmente: `npm install -g docsify-cli`
- Execute a partir do diretório raiz do repositório
- Verifique se `docs/_sidebar.md` existe

### Dicas para Ambiente de Desenvolvimento

- Use VS Code com a extensão Live Server para projetos HTML
- Instale as extensões ESLint e Prettier para formatação consistente
- Use as DevTools do navegador para depurar JavaScript
- Para projetos Vue, instale a extensão Vue DevTools no navegador

### Considerações de Desempenho

- Grande número de arquivos traduzidos (50+ idiomas) significa clones completos grandes
- Use clone superficial se estiver trabalhando apenas no conteúdo: `git clone --depth 1`
- Exclua traduções das buscas ao trabalhar no conteúdo em inglês
- Processos de build podem ser lentos na primeira execução (npm install, build do Vite)

## Considerações de Segurança

### Variáveis de Ambiente

- Chaves de API nunca devem ser comprometidas no repositório
- Use arquivos `.env` (já em `.gitignore`)
- Documente as variáveis de ambiente necessárias nos READMEs dos projetos

### Projetos em Python

- Use ambientes virtuais: `python -m venv venv`
- Mantenha as dependências atualizadas
- Tokens do GitHub devem ter permissões mínimas necessárias

### Acesso aos Modelos do GitHub

- Tokens de Acesso Pessoal (PAT) são necessários para os Modelos do GitHub
- Tokens devem ser armazenados como variáveis de ambiente
- Nunca comprometa tokens ou credenciais

## Notas Adicionais

### Público-alvo

- Iniciantes completos em desenvolvimento web
- Estudantes e autodidatas
- Professores usando o currículo em salas de aula
- O conteúdo é projetado para acessibilidade e construção gradual de habilidades

### Filosofia Educacional

- Abordagem de aprendizado baseada em projetos
- Verificações frequentes de conhecimento (quizzes)
- Exercícios práticos de codificação
- Exemplos de aplicação no mundo real
- Foco nos fundamentos antes de frameworks

### Manutenção do Repositório

- Comunidade ativa de alunos e contribuidores
- Atualizações regulares de dependências e conteúdo
- Issues e discussões monitoradas pelos mantenedores
- Atualizações de tradução automatizadas via GitHub Actions

### Recursos Relacionados

- [Módulos do Microsoft Learn](https://docs.microsoft.com/learn/)
- [Recursos do Student Hub](https://docs.microsoft.com/learn/student-hub/)
- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) recomendado para alunos
- Cursos adicionais: IA Generativa, Ciência de Dados, ML, currículos de IoT disponíveis

### Trabalhando com Projetos Específicos

Para instruções detalhadas sobre projetos individuais, consulte os arquivos README em:
- `quiz-app/README.md` - Aplicativo de quiz em Vue 3
- `7-bank-project/README.md` - Aplicativo bancário com autenticação
- `5-browser-extension/README.md` - Desenvolvimento de extensão de navegador
- `6-space-game/README.md` - Desenvolvimento de jogo baseado em Canvas
- `9-chat-project/README.md` - Projeto de assistente de chat com IA

### Estrutura de Monorepo

Embora não seja um monorepo tradicional, este repositório contém vários projetos independentes:
- Cada aula é autônoma
- Projetos não compartilham dependências
- Trabalhe em projetos individuais sem afetar outros
- Clone o repositório inteiro para a experiência completa do currículo

---

**Aviso Legal**:  
Este documento foi traduzido utilizando o serviço de tradução por IA [Co-op Translator](https://github.com/Azure/co-op-translator). Embora nos esforcemos para garantir a precisão, esteja ciente de que traduções automatizadas podem conter erros ou imprecisões. O documento original em seu idioma nativo deve ser considerado a fonte oficial. Para informações críticas, recomenda-se a tradução profissional realizada por humanos. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações equivocadas decorrentes do uso desta tradução.