Guide de Contribution - Traductions

🎯 Objectif

Aider la communauté francophone à contribuer aux traductions de la documentation du Hexagonal Maker Bundle.

📊 État Actuel des Traductions

✅ Complùtement Traduit

  • Page d’accueil (index.md ↔ fr/index.md)

🔄 Partiellement Traduit

  • Guide Architecture (ARCHITECTURE.md - version française existe)

❌ À Traduire (PrioritĂ© Haute)

Les 9 nouveaux guides avancés créés sont en anglais et nécessitent une traduction :

  1. Domain vs Application Logic (advanced/domain-vs-application.md)
    • Guide de dĂ©cision crucial pour les dĂ©veloppeurs
    • ~26 KB de contenu
    • Contient des flowcharts et exemples de code
  2. Request-Response Flow (advanced/request-response-flow.md)
    • Flux complet end-to-end avec diagrammes
    • ~24 KB de contenu
    • Diagrammes Mermaid sĂ©quentiels
  3. Port Design Principles (advanced/port-design-principles.md)
    • Principes de conception des interfaces
    • ~21 KB de contenu
    • Exemples comparatifs ✅/❌
  4. Primary vs Secondary Adapters (advanced/primary-secondary-adapters.md)
    • Les deux cĂŽtĂ©s de l’hexagone
    • ~22 KB de contenu
    • Diagrammes d’architecture
  5. CQRS: Cost-Benefit Analysis (advanced/cqrs-cost-benefit.md)
    • Analyse coĂ»ts/bĂ©nĂ©fices CQRS
    • ~26 KB de contenu
    • Flowchart de dĂ©cision
  6. Dependency Injection Guide (advanced/dependency-injection-guide.md)
    • Configuration Symfony complĂšte
    • ~25 KB de contenu
    • Exemples de configuration YAML
  7. Factory Pattern Guide (advanced/factory-pattern-guide.md)
    • ImplĂ©mentation complĂšte des factories
    • ~27 KB de contenu
    • Patterns multiples avec exemples
  8. Error Handling Strategy (advanced/error-handling-strategy.md)
    • Gestion des exceptions
    • ~24 KB de contenu
    • HiĂ©rarchie d’exceptions
  9. Anti-Patterns & Pitfalls (advanced/anti-patterns-pitfalls.md)
    • Erreurs courantes Ă  Ă©viter
    • ~25 KB de contenu
    • Comparaisons ❌ mauvais vs ✅ bon

Total Ă  traduire : ~220 KB de documentation technique

🚀 Comment Contribuer

Étape 1 : Choisir un Document

Consultez la liste ci-dessus et choisissez un document à traduire. Les guides sont indépendants, vous pouvez en choisir un seul.

Étape 2 : Forker le DĂ©pĂŽt 

# Fork sur GitHub, puis clone
git clone https://github.com/VOTRE-USERNAME/hexagonal-maker-bundle.git
cd hexagonal-maker-bundle
git checkout -b traduction-domain-vs-application

Étape 3 : CrĂ©er la Structure 

# Créer le dossier si nécessaire
mkdir -p docs/fr/advanced

# Copier le fichier source
cp docs/advanced/domain-vs-application.md docs/fr/advanced/domain-vs-application.md

Étape 4 : Traduire le Contenu

Ouvrez docs/fr/advanced/domain-vs-application.md et commencez la traduction.

Front Matter (En-tĂȘte YAML) 

---
layout: default
title: Domain vs Application Logic  # ← Traduire le titre
parent: Sujets AvancĂ©s             # ← Traduire "Advanced Topics"
nav_order: 10
lang: fr                            # ← Changer 'en' en 'fr'
lang_ref: advanced/domain-vs-application.md  # ← Chemin vers version anglaise
---

Contenu Markdown

À traduire :

  • Titres et sous-titres
  • Paragraphes explicatifs
  • Commentaires dans les exemples de code
  • LĂ©gendes des diagrammes
  • Tableaux et listes

À NE PAS traduire :

  • Noms de variables et fonctions dans le code
  • Mots-clĂ©s du langage (class, public, function, etc.)
  • URLs et chemins de fichiers
  • Noms de classes PHP
  • Diagrammes Mermaid (sauf labels/textes)

📝 Rùgles de Traduction

1. Terminologie Technique

Utilisez ces traductions cohérentes :

English Français
Port Port (garder en anglais dans contexte technique)
Adapter Adaptateur
Domain Domaine
Application Layer Couche Application
Infrastructure Infrastructure
Handler Handler (garder en anglais)
Repository Repository (ou DĂ©pĂŽt)
Value Object Value Object (ou Objet-Valeur)
Entity Entité
Use Case Cas d’Usage
Command Commande
Query RequĂȘte (ou Query en contexte CQRS)
Factory Fabrique (ou Factory)
Dependency Injection Injection de DĂ©pendances

2. Termes Ă  Garder en Anglais

Certains termes sont mieux reconnus en anglais :

  • CQRS (Command Query Responsibility Segregation)
  • SOLID (principes)
  • Design Patterns (ou Patterns de Conception)
  • Hexagonal Architecture
  • Ports & Adapters
  • DTO (Data Transfer Object)

3. Code et Exemples

✅ BIEN :

// ✅ BON : La logique mĂ©tier dans l'entitĂ©
class Order
{
    public function ship(): void
    {
        if ($this->status === OrderStatus::CANCELLED) {
            throw new CannotShipCancelledOrderException();
        }

        $this->status = OrderStatus::SHIPPED;
    }
}

Notez :

  • Commentaire traduit : “BON : La logique mĂ©tier dans l’entitĂ©â€
  • Code non traduit : class Order, ship(), etc.

4. Titres de Sections

Traduisez les titres mais gardez la structure :

Anglais :

## The Problem: Anemic Domain Model

Français :

## Le ProblÚme : ModÚle de Domaine Anémique

5. Diagrammes Mermaid

Traduisez uniquement les labels/textes :

Anglais :

graph TD
    Start[Logic to implement] --> Q1{Is it a business rule?}
    Q1 -->|Yes| Domain[DOMAIN LAYER]
    Q1 -->|No| Application[APPLICATION LAYER]

Français :

graph TD
    Start[Logique à implémenter] --> Q1{Est-ce une rÚgle métier ?}
    Q1 -->|Oui| Domain[COUCHE DOMAINE]
    Q1 -->|Non| Application[COUCHE APPLICATION]

6. Tableaux

Traduisez les en-tĂȘtes et le contenu :

Anglais :

| Question | Domain | Application |
|----------|--------|-------------|
| Is it a business rule? | ✅ | ❌ |

Français :

| Question | Domaine | Application |
|----------|---------|-------------|
| Est-ce une rĂšgle mĂ©tier ? | ✅ | ❌ |

🎹 Style et Ton

Ton Général

  • Formel mais accessible : Utilisez “vous” (tutoiement possible si cohĂ©rent avec le reste)
  • Technique mais clair : Expliquez les concepts complexes simplement
  • Didactique : La documentation est pĂ©dagogique, gardez cet esprit

Exemples de Style

Anglais :

“If you need to validate input, use value objects.”

❌ Mauvaise traduction :

“Si tu as besoin de valider l’input, utilise des value objects.”

✅ Bonne traduction :

“Si vous devez valider les donnĂ©es d’entrĂ©e, utilisez des value objects.”

đŸ§Ș Tester Votre Traduction

1. Installation Locale de Jekyll 

cd docs
bundle install

2. Lancer le Serveur Local 

bundle exec jekyll serve

3. VĂ©rifier

  • Ouvrez http://localhost:4000
  • Naviguez vers votre page traduite
  • VĂ©rifiez le language switcher (🇬🇧 ↔ đŸ‡«đŸ‡·)
  • Testez les liens internes
  • VĂ©rifiez le rendu des diagrammes Mermaid

4. Checklist de Validation

  • Front matter correct (lang: fr)
  • Titre traduit
  • Navigation fonctionne
  • Language switcher fonctionne
  • Liens internes corrects
  • Diagrammes s’affichent correctement
  • Code s’affiche avec coloration syntaxique
  • Tableaux bien formatĂ©s
  • Pas de fautes d’orthographe/grammaire

đŸ“€ Soumettre Votre Traduction

1. Commit et Push 

git add docs/fr/advanced/domain-vs-application.md
git commit -m "feat(docs): add French translation for Domain vs Application Logic"
git push origin traduction-domain-vs-application

2. Créer une Pull Request

  • Allez sur GitHub
  • Cliquez sur “New Pull Request”
  • Titre : docs(fr): traduction Domain vs Application Logic
  • Description : 
    ## Description
Traduction française du guide "Domain vs Application Logic"

## Checklist
- [x] Front matter correct
- [x] Contenu traduit
- [x] Diagrammes traduits
- [x] Testé localement
- [x] Liens fonctionnels

3. Review

Le mainteneur reviewera votre traduction et pourra demander des ajustements.

🎯 PrioritĂ©s de Traduction

Si vous ne savez pas par oĂč commencer, voici l’ordre de prioritĂ© suggĂ©rĂ© :

đŸ”„ PrioritĂ© Haute

  1. Domain vs Application Logic - Le guide le plus important pour les débutants
  2. Anti-Patterns & Pitfalls - Éviter les erreurs courantes
  3. Request-Response Flow - Comprendre le flux complet

⚡ PrioritĂ© Moyenne

  1. Port Design Principles - Conception des interfaces
  2. Primary vs Secondary Adapters - Les deux cĂŽtĂ©s de l’hexagone
  3. Error Handling Strategy - Gestion des erreurs

💡 PrioritĂ© Basse

  1. CQRS: Cost-Benefit Analysis - Concept avancé
  2. Dependency Injection Guide - Configuration technique
  3. Factory Pattern Guide - Pattern spécifique

đŸ€ Besoin d’Aide ?

Questions

Si vous avez des questions sur :

  • La terminologie Ă  utiliser
  • L’ambiguĂŻtĂ© d’un terme
  • La meilleure façon de traduire un concept

Créez une issue sur GitHub avec le label traduction :

  • Titre : [Traduction] Question sur terme "X"
  • DĂ©crivez votre question avec contexte

Glossaire Collaboratif

Un glossaire FR/EN est maintenu dans : docs/fr/GLOSSAIRE.md

Consultez-le avant de traduire et contribuez-y si vous trouvez de nouveaux termes.

📊 Suivi de Progression

Tableau de Bord

Guide Taille Traducteur Statut PR
Domain vs Application 26 KB - ❌ À faire -
Request-Response Flow 24 KB - ❌ À faire -
Port Design Principles 21 KB - ❌ À faire -
Primary vs Secondary 22 KB - ❌ À faire -
CQRS Cost-Benefit 26 KB - ❌ À faire -
Dependency Injection 25 KB - ❌ À faire -
Factory Pattern 27 KB - ❌ À faire -
Error Handling 24 KB - ❌ À faire -
Anti-Patterns 25 KB - ❌ À faire -

LĂ©gende

  • ❌ À faire - Pas encore commencĂ©
  • 🔄 En cours - Traduction en cours
  • ✅ TerminĂ© - Traduit et mergĂ©
  • 🔍 Review - En attente de review

🌟 Remerciements

Merci à tous les contributeurs qui aident à rendre cette documentation accessible à la communauté francophone !

Votre nom sera ajouté dans :

  • Le fichier CONTRIBUTORS.md
  • La section “Contributeurs” de la documentation
  • Les release notes

Questions ? Ouvrez une issue avec le label question ou contactez @ahmed-bhs

PrĂȘt Ă  contribuer ? Choisissez un guide dans la liste ci-dessus et lancez-vous ! 🚀