docs: add a doc for presenting dos and donts for translations

docs/translations.md

@@ -0,0 +1,52 @@
+
+# Traductions
+
+Il ne faut pas :
+* mettre d'URL dans les fichiers de traduction
+
+Il faut éviter de :
+* mettre du HTML dans les fichiers de traduction
+
+Il faut privilégier :
+* les traitements basés sur la notion de locale plutôt que les traitements basés
+  sur la notion de langue, cf. ADR
+  [Logique et stratégie de gestion des paramètres régionaux et des langues (locales & languages)](https://github.com/1024pix/pix/blob/dev/docs/adr/0040-locales-languages.md)
+* la gestion générique de toutes les locales
+* les phrases et paragraphes auto-porteurs et indépendants
+
+
+## Contexte et explications
+
+Couplage et complexité : les fichiers de traduction sont conçus pour gérer le
+texte et pas la logique applicative (notamment la logique applicative des URL)
+Quand la logique applicative des URL change on doit évider de modifier tous les
+fichiers de traduction (et plus le nombre de locales sera élevé et plus cette
+tâche serait difficile.
+
+Manque de flexibilité : parfois les URL nécessitent d'être dynamiques (query
+params...).
+
+Les traducteurs ne devraient pas avoir à gérer des URL. Et en plus ils peuvent facilement faire des erreurs en copiant des URL … ou pire … vouloir traduire les URL 😱
+
+Et puis pour créer les URL il peut être nécessaire de les construire en fonction
+de plein de choses : la locale, le domaine, etc.
+
+
+## Solutions
+
+### Pour les frontaux
+
+Utilisez l'urlService disponible dans tous les frontaux (Pix App, Pix Orga, Pix
+Certif, Pix Admin).
+
+Exemple : https://github.com/1024pix/pix/pull/10974
+
+### Pour Pix API
+
+Il y a beaucoup beaucoup moins de besoins de traduction dans Pix API, mais un
+[`api/src/shared/infrastructure/utils/url-builder.js`](https://github.com/1024pix/pix/blob/dev/api/src/shared/infrastructure/utils/url-builder.js)
+est disponible.
+
+
+
+