Skip to content
AMN Docs

Dossier d'Architecture Technique (DAT)

Dossier d'Architecture Technique (DAT)

Documentation technique

Couche 02 : Présentation (Rendu et Front-End)

Projet : Réarchitecture du Site Web (Vitrine, Blog, Portfolio, Documentation)
Statut : Version 1.4 (Fine-tuning L2 – Complet)
Date : 2 Septembre 2026
Équipe : Architecture IT

1. Introduction & Objectifs

Ce document spécifie les standards, la structure et les mécanismes de fonctionnement de la Couche 02 (Présentation). Cette couche est responsable de la récupération des données issues de la Couche 01 (Sanity et fichiers locaux), de leur transformation, de leur mise en page et de leur distribution optimisée aux utilisateurs finaux via un rendu hybride.

2. Architecture de Rendu & Configuration du Framework

Le projet utilise Astro configuré avec l’adaptateur Cloudflare (@astrojs/cloudflare) pour activer les fonctionnalités dynamiques. Ce choix garantit un alignement strict avec la Couche 03 (Pages Functions, Workers et Middleware Cloudflare).

2.1. Fichier de Configuration Core (astro.config.mjs)1/3

Le framework est paramétré en mode hybrid. Ce choix stratégique impose le comportement suivant :

  • Par défaut, toutes les pages sont compilées en HTML Statique (SSG) au moment du build.
  • Les pages nécessitant une logique serveur à la volée activent explicitement le Rendu Serveur (SSR).

2.1. Fichier de Configuration Core (astro.config.mjs)2/3

import { defineConfig } from 'astro/config';
import tailwind from '@astrojs/tailwind';
import sanity from '@sanity/astro';
import starlight from '@astrojs/starlight';
import cloudflare from '@astrojs/cloudflare';


export default defineConfig({
  output: 'hybrid',
  adapter: cloudflare({
    // Mode recommandé pour Pages + Functions
    platformProxy: {
      enabled: true, // Facilite le développement local avec Wrangler
    },
  }),
  integrations: [
    tailwind(),
    sanity({
      projectId: 'votre_project_id',
      dataset: 'production',
      useCdn: true, // CDN Sanity pour le build SSG
      // Le client sera reconfiguré dynamiquement en mode preview (voir §5.3)
    }),
    starlight({
      title: 'Documentation Technique',
      sidebar: [
        { label: 'Guide de Démarrage', autogenerate: { directory: 'guide' } },
        { label: 'Références API', autogenerate: { directory: 'api' } },
      ],
    }),
  ],
});

2.1. Fichier de Configuration Core (astro.config.mjs)3/3

Alignement avec la Couche 03 : L’adaptateur @astrojs/cloudflare est obligatoire. Il compile les routes prerender = false en Cloudflare Pages Functions et s’intègre nativement avec le Middleware Worker et les Workers métiers définis en L3.

3. Structure de l’Espace de Travail (Workspace)

L’arborescence du projet est rationalisée pour séparer les structures de pages globales de la logique applicative de Starlight :

├── src/
│   ├── components/       # Composants d'interface réutilisables (Boutons, Cartes, etc.)
│   │   ├── ui/           # Composants atomiques (HTML purs)
│   │   └── interactive/  # Îlots dynamiques (React/Vue/Svelte si nécessaire)
│   ├── content/          # Définition des schémas de données locaux
│   │   ├── config.ts     # Validation Zod des schémas de contenu
│   │   └── docs/         # Fichiers Markdown/MDX consommés par Starlight
│   ├── layouts/          # Gabarits de page globaux (Header, Footer, Meta SEO)
│   │   ├── MainLayout.astro
│   │   └── BlogLayout.astro
│   └── pages/            # Système de routage du site principal
│       ├── index.astro   # Page d'accueil (Vitrine) - [SSG]
│       ├── blog/
│       │   ├── index.astro     # Liste des articles - [SSG]
│       │   └── [slug].astro    # Article unitaire dynamique au build - [SSG]
│       ├── portfolio/
│       │   └── index.astro     # Galerie de projets - [SSG]
│       └── contact.astro       # Exemple de page avec traitement de formulaire - [SSR]
├── astro.config.mjs
└── package.json

4. Stratégie d’Hydratation & Gestion du JavaScript (Îlots)1/2

Afin de préserver des performances maximales (Score Lighthouse / Core Web Vitals proche de 100), la couche de présentation applique strictement la politique de l’Architecture en Îlots :

  • Rendu HTML Statique (Par défaut) : Les en-têtes, textes de la vitrine, articles de blog et pages de documentation n’embarquent aucun framework JS.

4. Stratégie d’Hydratation & Gestion du JavaScript (Îlots)2/2

  • Hydratation ciblée (Îlots interactifs) : Lorsqu’un composant requiert du JavaScript côté client, l’hydratation est explicitement déclarée et différée selon le besoin :
    • client:load : Pour les éléments immédiatement critiques (ex: un menu de navigation mobile interactif).
    • client:visible : Pour les éléments plus bas dans la page (ex: un carrousel de témoignages sur la vitrine ou un graphique dans le portfolio). Le JS n’est chargé que lorsque l’élément entre dans le viewport.

5. Intégration et Consommation de la Couche 01

5.1. Récupération des données Sanity (Vitrine, Blog, Portfolio)1/2

Les requêtes vers le Content Lake de Sanity s’exécutent côté serveur (au moment du build pour le SSG ou à la requête pour le SSR) à l’aide de l’outil de requêtage GROQ.

5.1. Récupération des données Sanity (Vitrine, Blog, Portfolio)2/2

---
// Exemple d'implémentation dans src/pages/blog/[slug].astro
import MainLayout from '../../layouts/MainLayout.astro';
import { getSanityClient } from '../../lib/sanity';


export async function getStaticPaths() {
  // En phase de build SSG, on force toujours la perspective "published"
  const client = getSanityClient({
    cookies: { get: () => undefined },
    request: { headers: { get: () => null } }
  } as any);


  const posts = await client.fetch(`*[_type == "post" && status == "published"]{ "slug": slug.current }`);
  return posts.map((post) => ({ params: { slug: post.slug } }));
}


const sanityClient = getSanityClient(Astro); // Détecte automatiquement le mode Preview si présent
const { slug } = Astro.params;
const post = await sanityClient.fetch(
  `*[_type == "post" && slug.current == $slug][0]{ title, publishedAt, body }`,
  { slug }
);
---
<MainLayout title={post.title}>
  <article>
    <h1>{post.title}</h1>
    <p>Publié le {new Date(post.publishedAt).toLocaleDateString()}</p>
    <!-- Rendu du texte riche via un composant portable text -->
  </article>
</MainLayout>

5.2. Isolation de la Documentation (Starlight)

L’intégration de Starlight intercepte automatiquement la route /docs. Elle valide de manière autonome les fichiers Markdown situés dans src/content/docs/ en se basant sur ses propres schémas de métadonnées (frontmatter).

5.3. Gestion du mode Preview (Draft Mode)

La prévisualisation des contenus Sanity en brouillon est entièrement pilotée par le Middleware Cloudflare (voir DAT L1 §4.7 et DAT L3 §3.1).
Astro n’a qu’un rôle de détection et de reconfiguration du client Sanity.

5.3.1. Détection du mode Preview

Astro détecte la présence du cookie sanity-preview=true (posé par le Middleware) ou du header x-sanity-preview: true.

// src/lib/sanity.ts (ou utilitaire équivalent)
import { createClient } from '@sanity/client';
import type { AstroGlobal } from 'astro';


export function getSanityClient(astro: AstroGlobal) {
  const isPreview =
    astro.cookies.get('sanity-preview')?.value === 'true' ||
    astro.request.headers.get('x-sanity-preview') === 'true';


  return createClient({
    projectId: import.meta.env.PUBLIC_SANITY_PROJECT_ID,
    dataset: import.meta.env.PUBLIC_SANITY_DATASET,
    apiVersion: '2025-01-01',
    useCdn: !isPreview,               // Désactive le CDN en preview
    perspective: isPreview ? 'previewDrafts' : 'published',
    token: isPreview
      ? import.meta.env.SANITY_API_READ_TOKEN // Token avec droit de lecture des drafts
      : undefined,
  });
}

5.3.2. Route de sortie du mode Preview

Une route dédiée permet de sortir du mode preview (suppression du cookie) :

src/pages/api/exit-preview.ts
---
export const prerender = false;


Astro.cookies.delete('sanity-preview', { path: '/' });
return Astro.redirect('/');
---

5.3.3. Règles importantes

  • Aucune page en mode Preview n’est jamais générée en SSG.
  • Les routes qui affichent du contenu Sanity doivent utiliser le client conditionnel ci-dessus.
  • Le token SANITY_API_READ_TOKEN (lecture drafts) est uniquement disponible en runtime (Pages Functions) et jamais exposé côté client.
  • La documentation Starlight n’est pas concernée par ce mécanisme.

5.4. Consommation et optimisation des médias (Cloudflare R2 + Stream)

Tous les médias sont stockés exclusivement sur Cloudflare R2 (images, documents) et Cloudflare Stream (vidéos). Sanity ne conserve que les métadonnées + URLs (voir DAT L1 §4.8).

5.4.1. Images

  • Source de vérité : URL publique R2 (ou URL signée si nécessaire).
  • Optimisation recommandée :
    • Utilisation de Cloudflare Polish (lossy/lossless) + Mirage activés sur la zone.
    • Pour un contrôle plus fin : Cloudflare Images (redimensionnement à la volée via /cdn-cgi/image/).
    • Côté Astro : composant <Image> personnalisé ou astro:assets avec un loader custom pointant vers R2 si besoin de transformation au build.
  • Bonnes pratiques obligatoires :
    • Toujours fournir width, height et alt.
    • Utiliser loading="lazy" + decoding="async" sauf pour les images LCP (Hero).
    • Générer des srcset / sizes pour le responsive.
    • Formats modernes : Cloudflare sert automatiquement WebP/AVIF selon le support navigateur.

5.4.2. Vidéos

  • Les vidéos sont hébergées sur Cloudflare Stream.
  • Astro n’embarque que le player Stream (iframe ou SDK officiel) à partir de l’UID stocké dans Sanity.
  • Aucun fichier vidéo n’est jamais servi directement depuis R2 en production.

5.4.3. Documents (PDF, etc.)

  • Lien direct vers l’URL R2.
  • Possibilité d’ajouter une prévisualisation (miniature générée par un Worker si besoin).

5.5. Typage fort (Sanity → Astro)

Afin d’éliminer le drift entre les schémas Sanity et le code Astro, un mécanisme de génération de types TypeScript est mis en place.

5.5.1. Outil retenu

  • sanity-typegen (officiel Sanity) ou équivalent (@sanity/codegen).
  • Les types sont générés à partir des schémas définis dans le projet sanity-studio.

5.5.2. Workflow

  1. Les schémas Sanity sont la source de vérité.
  2. Une commande (script npm + GitHub Action) génère les types TypeScript à chaque modification des schémas.
  3. Les types générés sont versionnés dans le dépôt Astro (src/types/sanity.d.ts ou équivalent).
  4. Toutes les requêtes GROQ et les composants qui consomment des données Sanity utilisent ces types.

5.5.3. Règles

  • Aucune donnée Sanity n’est manipulée avec le type any.
  • Les queries GROQ critiques sont typées (retour attendu).
  • Le pipeline CI échoue si les types générés ne sont pas à jour par rapport aux schémas.

6. Routage Dynamique (SSR) : Gestion des Exceptions

Par défaut, l’application génère du contenu statique. Pour les routes nécessitant une logique serveur temps réel (ex: un formulaire de contact, un moteur de recherche interne cross-sources, ou un espace privé), la directive de pré-rendu est désactivée.

6.1. Politique de cache des routes SSR1/3

Les routes déclarées avec export const prerender = false s’exécutent sur Cloudflare Pages Functions.

La politique de cache est gérée selon le principe de responsabilité suivant (aligné avec la L3) :

  1. Niveau Middleware Cloudflare (Worker indépendant)

    • Pose les headers de sécurité.
    • Applique une politique de cache par défaut.
    • Force Cache-Control: no-store dès que le mode Preview est actif (sanity-preview=true).

  2. Niveau page Astro (spécifique)
    Chaque page SSR peut affiner sa propre politique via Astro.response.headers :

6.1. Politique de cache des routes SSR2/3

Type de page SSR Cache-Control (navigateur) CDN-Cache-Control (Cloudflare)
Pages semi-dynamiques public, max-age=60 max-age=300, stale-while-revalidate=86400
Pages hautement dynamiques / privées private, no-store no-store
Pages de formulaire (GET) public, max-age=300 max-age=600, stale-while-revalidate=3600
Réponses d’actions (POST) no-store no-store

6.1. Politique de cache des routes SSR3/3

Exemple dans une page :

Astro.response.headers.set('Cache-Control', 'public, max-age=60');
Astro.response.headers.set('CDN-Cache-Control', 'max-age=300, stale-while-revalidate=86400');

6.2. Gestion des formulaires (exemple : Contact)

Les formulaires suivent un contrat strict entre la Couche 02 et la Couche 03 :

  1. Validation côté client (UX immédiate) avec Zod ou équivalent.
  2. Soumission vers le Worker form-handler (L3) via fetch (jamais de logique métier dans Astro).
  3. Protection anti-spam : Cloudflare Turnstile (recommandé) ou équivalent.
  4. Feedback utilisateur : états de chargement, succès et erreur clairement exposés.
  5. Accessibilité : labels explicites, messages d’erreur liés via aria-describedby, gestion du focus.

Exemple de flux recommandé

src/pages/contact.astro
---
export const prerender = false;


import { z } from 'zod';


const contactSchema = z.object({
  email: z.string().email(),
  message: z.string().min(10).max(2000),
});


let formState: 'idle' | 'loading' | 'success' | 'error' = 'idle';
let errorMessage = '';


if (Astro.request.method === 'POST') {
  formState = 'loading';
  try {
    const formData = await Astro.request.formData();
    const raw = Object.fromEntries(formData);
    const data = contactSchema.parse(raw);


    // Appel au Worker L3
    const res = await fetch('https://api.votredomaine.com/form-handler', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(data),
    });


    if (!res.ok) throw new Error('Erreur serveur');
    formState = 'success';
  } catch (err) {
    formState = 'error';
    errorMessage = err instanceof z.ZodError
      ? 'Veuillez vérifier les champs.'
      : 'Une erreur est survenue. Merci de réessayer.';
  }
}
---

Toute logique de validation métier lourde, d’envoi d’email ou d’intégration CRM reste dans le Worker form-handler (L3). Astro ne fait que l’orchestration front + validation de surface.

7. Pipeline de Déploiement et d’Invalidation

  1. Build initial : Le pipeline CI/CD compile le projet. Astro génère l’ensemble des fichiers HTML pour les routes statiques et prépare les fonctions Serverless pour les routes dynamiques (prerender = false).
  2. Déclenchement externe : Lorsqu’un contributeur publie un nouvel article sur Sanity, le webhook configuré sur le CMS émet une requête HTTP POST vers l’hébergeur pour relancer ce build. Le site statique est ainsi mis à jour sans interruption de service.

8. Stratégie de Recherche Unifiée (Pagefind)

La recherche doit couvrir de manière unifiée l’ensemble du contenu du site : Vitrine, Blog, Portfolio (sources Sanity) et Documentation (Starlight).

8.1. Solution retenue

Pagefind est adopté comme moteur de recherche unique pour les raisons suivantes :

  • Gratuit et open-source
  • Indexation statique au build (parfaitement aligné avec le mode SSG dominant)
  • Déjà intégré nativement dans Starlight
  • Excellent support Astro (astro-pagefind ou CLI)
  • Performance élevée grâce à l’index chunké (faible bande passante)
  • Zéro dépendance à un service externe

8.2. Fonctionnement

  1. Astro génère l’ensemble des pages HTML (SSG).
  2. Pagefind indexe le dossier dist/ immédiatement après le build.
  3. Un seul index couvre tout le site (contenu Sanity + documentation Starlight).
  4. L’index est régénéré automatiquement à chaque build (y compris ceux déclenchés par les webhooks Sanity).

8.3. Règles d’indexation

  • Inclus : toutes les pages publiées de la Vitrine, du Blog, du Portfolio et de la Documentation.
  • Exclus :
    • Pages en mode Preview / Draft
    • Routes techniques (/api/*, pages d’administration, etc.)
    • Éléments de navigation et footer (via exclude_selectors)

8.4. Expérience utilisateur & distinction visuelle des résultats

La barre de recherche globale (header du site) utilise Pagefind.

Les résultats sont visuellement distingués par type de contenu afin d’améliorer la lisibilité :

Type de contenu Badge / Indicateur visuel Exemple
Documentation Badge « Doc » Guide d’installation
Article de Blog Badge « Blog » Titre de l’article
Projet Portfolio Badge « Portfolio » Nom du projet
Page Vitrine Badge « Page » Titre de la page

Cette distinction est réalisée via les métadonnées Pagefind (filtres ou data-pagefind-meta) et un rendu custom de l’interface de résultats.

8.5. Cohérence avec Starlight

Starlight continue d’utiliser Pagefind nativement pour sa propre barre de recherche.
L’objectif est de partager le même index (ou des index très proches) afin d’offrir une expérience de recherche homogène sur l’ensemble du portail.

9. Gestion des erreurs et résilience

9.1. Principes

  • Aucune page ne doit planter complètement si Sanity est momentanément indisponible.
  • Les erreurs sont loggées et surveillées (via Cloudflare Logpush / Workers Analytics).
  • L’utilisateur final voit toujours une expérience dégradée élégante plutôt qu’une erreur 500 brute.

9.2. Stratégies par contexte

Contexte Comportement attendu
Build SSG (Sanity down) Le build échoue → alerte immédiate (CI + notification). Pas de déploiement partiel.
Route SSR (Sanity down) Affichage d’un fallback (contenu en cache si disponible, ou message « Contenu temporairement indisponible ») + status 503 ou 200 avec bannière.
Erreur GROQ partielle Les sections non critiques affichent un état vide ou un skeleton. Les sections critiques (Hero, etc.) utilisent un fallback statique.
Mode Preview En cas d’erreur d’authentification du token draft → redirection vers la version publiée + message.

9.3. Mise en œuvre technique

  • Utilisation de try/catch autour de toutes les requêtes Sanity critiques.
  • Composants d’erreur réutilisables (ErrorBoundary.astro ou équivalent côté Islands).
  • Pages d’erreur Astro personnalisées (src/pages/500.astro, 404.astro).
  • En production, les erreurs 5xx des Pages Functions sont remontées via Cloudflare et déclenchent une alerte (seuil à définir, ex. > 2 % sur 5 min).

9.4. Observabilité

  • Logs structurés des échecs de fetch Sanity (avec query GROQ anonymisée).
  • Corrélation possible avec les logs du Worker cms-webhook-receiver (L3).

10. Stratégie SEO

10.1. Principes

Le SEO est traité comme une responsabilité de premier niveau de la Couche 02.
Les objets seo définis dans les schémas Sanity (metaTitle, metaDescription, ogImage) constituent la source de vérité éditoriale. Astro se charge de les matérialiser correctement dans le HTML.

10.2. Éléments techniques obligatoires1/2

Élément Implémentation
Balises meta title, description, og:*, twitter:* générés dynamiquement à partir de l’objet seo Sanity (avec fallback intelligent sur le titre et l’extrait).
Canonical Balise <link rel="canonical"> systématique sur toutes les pages.
Sitemap Génération automatique via @astrojs/sitemap (ou équivalent). Inclut uniquement les contenus status == "published". Exclut les routes techniques et le mode Preview.
robots.txt Fichier statique + règles dynamiques si besoin (blocage des environnements de preview / staging).
Structured Data (JSON-LD)

10.2. Éléments techniques obligatoires2/2

  • Organization (global)
  • WebSite + SearchAction (pour la recherche)
  • Article / BlogPosting (articles)
  • CreativeWork ou Project (portfolio)
  • Injecté via un composant réutilisable <JsonLd />. | | Open Graph & Twitter Cards | Image OG prioritaire = seo.ogImage → sinon image principale du contenu → sinon image par défaut du site. |

10.3. Règles de fallback

  1. seo.metaTitle → sinon title du document
  2. seo.metaDescription → sinon excerpt / description → sinon truncation du body
  3. seo.ogImage → sinon mainImage / première image de galerie → sinon image de fallback globale

10.4. Performance SEO

  • Toutes les pages de contenu principal restent en SSG (Core Web Vitals optimaux).
  • Les images respectent les bonnes pratiques définies en §5.4 (dimensions, alt, formats modernes).
  • Pas de JavaScript bloquant sur le chemin critique de rendu.

11. Accessibilité (a11y)

11.1. Objectif

Conformité WCAG 2.1 niveau AA minimum sur l’ensemble du site (Vitrine, Blog, Portfolio, Documentation).

11.2. Règles de conception

  • Tous les composants ui/ et interactive/ doivent être accessibles par défaut (focus visible, contraste, labels, etc.).
  • Navigation clavier complète (Tab, Enter, Escape, flèches selon les patterns).
  • Gestion correcte des zones aria-* et des rôles ARIA uniquement quand nécessaire (éviter la sur-utilisation).
  • Textes alternatifs obligatoires sur toutes les images informatives (récupérés depuis Sanity ou fallback).
  • Respect des ratios de contraste (texte / fond) – à valider avec les design tokens.

11.3. Outils et contrôles

Moment Outil / Pratique
Développement eslint-plugin-jsx-a11y + tests manuels clavier
CI Lighthouse CI (score a11y ≥ 95) + axe-core
Revue de design Checklist WCAG 2.1 AA
Documentation Starlight hérite déjà de bonnes bases a11y ; vérifier la cohérence avec le reste du site

11.4. Points d’attention spécifiques

  • Modales / overlays (focus trap + restauration du focus)
  • Carrousels et composants Islands interactifs
  • Formulaires (labels, messages d’erreur liés, aria-invalid, aria-describedby)
  • Mode sombre (si implémenté) : contraste maintenu

12. Design System et cohérence visuelle

12.1. Objectifs

  • Garantir une expérience visuelle homogène entre la Vitrine, le Blog, le Portfolio et la Documentation (Starlight).
  • Faciliter la maintenance et l’évolution du design sans dette technique.

12.2. Structure recommandée

src/
├── styles/
│   ├── tokens.css          # Design tokens (couleurs, spacing, typographie, radii…)
│   ├── global.css
│   └── starlight-overrides.css  # Surcharges ciblées du thème Starlight
├── components/
│   ├── ui/                 # Composants atomiques purs (Button, Badge, Card…)
│   └── interactive/        # Îlots (carrousels, filtres, etc.)

12.3. Règles

  • Les design tokens sont la source de vérité (CSS variables ou équivalent).
  • Starlight utilise le même système de tokens via des overrides ciblés (pas de duplication de styles).
  • Les composants ui/ sont indépendants de tout framework JS (HTML + CSS purs autant que possible).
  • Documentation des composants (Storybook ou équivalent léger) recommandée pour les composants complexes.
  • Support du mode sombre (si prévu) via les tokens + prefers-color-scheme ou classe manuelle.

13. Analytics et observabilité front

13.1. Principes

  • Privacy-first (pas de cookies non essentiels sans consentement).
  • Mesure des Core Web Vitals en conditions réelles (RUM).
  • Alignement avec l’écosystème Cloudflare déjà retenu.

13.2. Stack recommandée

Besoin Solution recommandée Commentaire
Analytics de base Cloudflare Web Analytics Gratuit, sans cookie, natif
Analytics produit / événements Plausible ou Umami (self-hosté ou cloud) Privacy-friendly, léger
Core Web Vitals (RUM) Cloudflare Web Analytics + évent. SpeedCurve / Calibre Suivi LCP, INP, CLS
Error tracking front Cloudflare Workers Analytics + logs Ou Sentry léger si besoin avancé

13.3. Règles d’implémentation

  • Aucun script analytics n’est chargé en mode Preview.
  • Les scripts tiers sont chargés en defer / async et idéalement via un Îlot ou un composant dédié.
  • Consentement (si requis par la réglementation) géré de manière centralisée.

14. Stratégie de tests

14.1. Pyramide de tests

Niveau Périmètre Outils recommandés Fréquence
Unitaires Composants ui/ et utilitaires Vitest + Testing Library À chaque commit
Intégration Pages + requêtes Sanity (mockées) Vitest / Playwright component PR
End-to-End Parcours critiques (navigation, formulaire, recherche, preview) Playwright PR + nightly
Visuels Régression visuelle des composants clés Playwright + screenshots ou Chromatic PR
Accessibilité Score a11y + règles critiques axe-core + Lighthouse CI PR
Performance Lighthouse CI (LCP, INP, CLS…) Lighthouse CI PR

14.2. Règles

  • Les tests E2E couvrent au minimum : page d’accueil, article de blog, page portfolio, documentation, formulaire de contact, bascule Preview.
  • Les données Sanity sont mockées en environnement de test (pas d’appel réel au Content Lake).
  • Le pipeline CI bloque le merge si les tests critiques ou le score a11y/performance descendent sous les seuils définis.

15. Internationalisation (i18n)

Cette section est conditionnelle. Elle s’applique uniquement si le multi-langue est prévu dans la roadmap produit.

15.1. Principes

  • Starlight gère nativement l’i18n pour la documentation.
  • Le reste du site (Vitrine, Blog, Portfolio) doit suivre la même stratégie de routing et de content collections.
  • Pagefind doit pouvoir indexer et filtrer par langue.

15.2. Approche recommandée

Élément Stratégie
Routing Préfixe de locale (/fr/..., /en/...) ou domaine par langue
Contenu Sanity Documents localisés ou champs localisés selon le volume
Documentation Mécanisme natif Starlight
UI (labels, boutons…) Fichiers de traduction (JSON/YAML) + helper Astro
SEO hreflang, canonical par locale, sitemaps séparés ou indexés
Recherche (Pagefind) Index par langue ou filtres de locale

15.3. Décision à trancher

Avant d’implémenter, valider avec le produit :

  • Quelles langues sont prioritaires ?
  • Le contenu marketing sera-t-il traduit à 100 % ou partiellement ?
  • Faut-il un sélecteur de langue visible dès le lancement ?
Switch to normal mode

Contents

Built with StarlightPowered by Cloudflare