scripts/translate-wp-plugin/README.md

# WordPress PT-PT Translation System v1.0.0

Sistema eficiente de traduções WordPress para Português Europeu com correcção automática de marcas, conversão PT-BR→PT-PT e validação de qualidade.

## Quick Start

```bash
# 1. Inicializar base de dados (primeira vez)
python3 wp-translate-ptpt.py --init-db

# 2. Processar ficheiro individual
python3 wp-translate-ptpt.py /path/to/plugin-pt_PT.po

# 3. Processar biblioteca inteira (só marcas)
python3 wp-translate-ptpt.py --brands-only --batch /biblioteca/

# 4. Tradução completa de novo plugin
python3 wp-translate-ptpt.py /novo-plugin-pt_PT.po
```

## Features

✅ **Correcção automática de marcas** — Detecta "Formulários Fluentes" → "Fluent Forms"
✅ **98 marcas seed** — Fluent Forms, Rank Math, Elementor, WooCommerce, etc.
✅ **50+ regras PT-BR→PT-PT** — gerenciar→gerir, deletar→eliminar, senha→palavra-passe
✅ **Cache SQLite** — Traduções reutilizadas, processamento rápido
✅ **Validação qualidade** — Preserva placeholders (%s, %d) e HTML tags
✅ **Batch processing** — Centenas de ficheiros em segundos
✅ **Backup/rollback** — Reversão automática em caso de erro
✅ **Compilação .mo** — Automática e tolerante a erros

## Arquitectura

### 6 Classes Core

```
BrandProtector       → Detecta e corrige marcas traduzidas literalmente
TranslationEngine    → LibreTranslate API wrapper com retry
PoFileHandler        → Parser/writer ficheiros .po
CacheManager         → SQLite cache + auditoria
QualityValidator     → Validação placeholders/HTML/PT-BR
TranslationProcessor → Orquestrador pipeline 9 etapas
```

### Pipeline de 9 Etapas

```
1. Parse .po → PoEntry objects
2. Brand protection (pre-translation)
3. Filter (cache check)
4. Translate (LibreTranslate)
5. Restore brands
6. PT-BR fixes
7. Brand correction (post-translation)
8. Quality validation
9. Save + compile .mo
```

## Modos de Uso

### Single File
```bash
python3 wp-translate-ptpt.py /path/to/plugin-pt_PT.po
```

### Batch Processing
```bash
python3 wp-translate-ptpt.py --batch /biblioteca/
```

### Brands Only (sem traduzir, só corrigir marcas)
```bash
python3 wp-translate-ptpt.py --brands-only ficheiro.po
python3 wp-translate-ptpt.py --brands-only --batch /biblioteca/
```

### Dry Run (simular sem alterar)
```bash
python3 wp-translate-ptpt.py --dry-run ficheiro.po
```

### Database Management
```bash
# Inicializar
python3 wp-translate-ptpt.py --init-db

# Exportar marcas
python3 wp-translate-ptpt.py --export-brands brands.json

# Importar marcas
python3 wp-translate-ptpt.py --import-brands brands.json
```

## Base de Dados SQLite

**Localização:** `wp-translations.db`

### 3 Tabelas

```sql
brands        → 98 marcas seed + auto-detectadas
translations  → Cache traduções (MD5 hash lookup)
corrections   → Log auditoria de todas as correcções
```

## Marcas Seed (98 total)

```
Fluent Forms, FluentCRM, Fluent SMTP, Rank Math, Elementor,
Elementor Pro, WooCommerce, WPForms, Wordfence, UpdraftPlus,
WP Rocket, Loco Translate, Bit Integrations, Element Pack,
ElementsKit, Happy Addons, Real Cookie Banner, Google,
Facebook, Instagram, PayPal, Stripe, WordPress, ...
```

## Conversões PT-BR → PT-PT (50+ regras)

```python
salvar       → guardar
deletar      → eliminar
gerenciar    → gerir
senha        → palavra-passe
arquivo      → ficheiro
atualiz*     → actualiz*
voce         → o utilizador
habilitar    → activar
desabilitar  → desactivar
cadastro     → registo
```

## Traduções Literais Detectadas (15+)

```python
"Fluent Forms" → ["Formulários Fluentes", "Formas Fluentes"]
"Rank Math"    → ["Matemática de Classificação"]
"Happy Addons" → ["Complementos Felizes"]
"Wordfence"    → ["Cerca de Palavras"]
"Element Pack" → ["Pacote de Elementos"]
```

## Performance

**Teste individual (FluentForm):**
- 53 marcas corrigidas
- Tempo: 1.2s

**Batch (241 ficheiros):**
- 15 marcas corrigidas
- Tempo: 42.8s
- Velocidade: ~5.6 ficheiros/segundo

## Dependências

```bash
pip install requests  # LibreTranslate API
# gettext tools (msgfmt) - já incluído na maioria das distros Linux
```

## Configuração LibreTranslate

**API URL (default):** `https://translate.descomplicar.pt/translate`
**Auth:** Whitelist IP (sem API key)
**Rate limit:** 0.3s entre chamadas

## Troubleshooting

### Erros msgfmt
Alguns ficheiros têm erros msgfmt pré-existentes (placeholders perdidos, headers inválidos). O script continua processamento e avisa, mas não falha.

### Ficheiros duplicados
A biblioteca pode ter duplicados em diferentes localizações. O script processa todos.

### Cache
Para limpar cache: `rm wp-translations.db` e executar `--init-db` novamente.

## Ficheiros

```
wp-translate-ptpt.py       → Script principal (~950 linhas)
wp-translations.db         → Base de dados SQLite
CHANGELOG.md               → Histórico de versões
REPORT-FINAL-*.md          → Reports de execução
README.md                  → Esta documentação
```

## Scripts Anteriores

Este script substitui:
- `translate-wordpress-plugin.py` (v1.0)
- `translate_missing.py` (v2.0 LibreTranslate)
- `fix_ptbr.py` (conversões PT-BR)
- `fix_malformed.py` (correcções sintaxe)

## Próximos Passos

1. **Manutenção mensal:**
   ```bash
   python3 wp-translate-ptpt.py --brands-only --batch /biblioteca/
   ```

2. **Novos plugins:**
   ```bash
   python3 wp-translate-ptpt.py /novo-plugin-pt_PT.po
   ```

3. **Auditoria PT-BR:**
   ```bash
   grep -r "gerenciar\|deletar\|voce" *.po
   ```

## Contribuir

1. Adicionar novas marcas: editar `SEED_BRANDS` (linha ~800)
2. Adicionar regras PT-BR: editar `PTBR_TO_PTPT` (linha ~400)
3. Adicionar mapeamentos literais: editar `LITERAL_TRANSLATIONS` (linha ~200)

## Versão

**v1.0.0** — 2026-02-23

**Autor:** Descomplicar® Crescimento Digital
**Licença:** Proprietário
**Python:** 3.8+