Bonne Pratique

Pour le WEB

Ex: pour une balise <h2/> avec une ancre

label-in-current-language

Les LLM sont plus efficaces que les humains pour protéger les liens, et LSDE vous permet de détecter les problèmes entre les différentes versions linguistiques.
Ainsi, vous pouvez partager un lien qui fonctionnera dans toutes les langues et utiliser LSDE pour gérer le remplacement d'une ancre dépréciée.

Ambiguïté du code

Évitez les ambiguïtés lorsque vous travaillez avec des modèles orientés données.
Exemple :
Mauvaise pratique : Le terme 'key' n'est pas explicite et rend sa recherche difficile.

ts
const PRODUCTS: Product[] = [
	{
		id: 'fcf7o',
		logo: '/icons/fcf7o-icon-40.webp',
		label: 'FCF7O',
		key: 'game:fcf7o.words.game_title',
	},
	{
		id: 'lsde',
		logo: '/icons/lsde-icon-40.webp',
		label: '<c1>LSDE</c1>',
		key: 'software:lsde.name',
	},
	{
		id: 'lsge',
		logo: '/icons/lsge.webp',
		label: 'LSGE',
		key: 'software:lsge.name',
	},
];

Bonne pratique : Adoptez une convention unique et cohérente.
Le terme i18nKey est très explicite et permet une recherche précise de cette valeur via des expressions régulières (Regex).

ts
const PRODUCTS: Product[] = [
	{
		id: 'fcf7o',
		logo: '/icons/fcf7o-icon-40.webp',
		label: 'FCF7O',
		i18nKey: 'game:fcf7o.words.game_title',
	},
	{
		id: 'lsde',
		logo: '/icons/lsde-icon-40.webp',
		label: '<c1>LSDE</c1>',
		i18nKey: 'software:lsde.name',
	},
	{
		id: 'lsge',
		logo: '/icons/lsge.webp',
		label: 'LSGE',
		i18nKey: 'software:lsge.name',
	},
];

Paresse

Les mauvaises idées naissent de la paresse.

Ne cherchez pas à économiser des clés en effectuant des opérations pour récupérer du contenu.
Exemple :

javascript
const [title, subtitle] = t( 'game:game.title' ).split( /[:：]/ );

C'est une fausse bonne idée, car dans certaines langues, les caractères peuvent varier et l'ordre des mots peut changer.

Format des balises

Réduisez au maximum le code destiné au design directement dans le texte, afin de le contrôler depuis le codebase.
Par exemple, vous pouvez indiquer l'emplacement d'une image, mais pas son style ou la manière dont elle doit être rendue.
Si vous devez apporter des modifications de design, vous ne voulez pas être contraint de retraduire un texte dans 10 langues juste pour changer le style d'une balise !

Les balises peuvent inclure un identifiant, mais ajouter des informations supplémentaires est généralement fortement déconseillé et constitue une mauvaise pratique.
Exemple : Ne faites pas
<img src='url' left />
mais plutôt
<img id=1 />
Vous récupérerez ensuite l'ID de la balise image pour lui appliquer les styles nécessaires dans le codebase.
Les ID doivent être utilisés littéralement et non via leur index.
En effet, dans différentes langues, les balises pourraient être déplacées et ne plus correspondre à l'index initial.
L'utilisation d'index naturels introduit également de la complexité pour le développeur ; essayer de deviner à quel index l'image ou la balise correspond est un véritable casse-tête.
Utilisez donc des balises avec un identifiant lorsque vous souhaitez pouvoir les personnaliser après interpolation.

CSS

Pour la traduction d'un site, lorsque vous avez des paragraphes, optez pour une hauteur minimale (`min-height`) après traduction afin d'éviter les décalages visuels lors des changements de langue.
Ex: `mih={'3lh'}`
Cela vous permet de définir une hauteur minimale basée sur la langue qui occupe le plus de lignes, garantissant ainsi une expérience utilisateur (UX) cohérente et sobre.

Namespace

Cela facilite grandement la mise en place d'un motif Regex pour retrouver vos clés.
Ex: game:a.b.c, common:a.b.c

Gestion de versions GIT

Les projets .lsde sont des fichiers au format JSON, ce qui facilite leur versionnement avec des outils comme Git.
Il est vivement recommandé d'enregistrer votre projet au sein d'un dépôt Git pour bénéficier d'un historique complet et d'une sécurité accrue.
Bien que LSDE intègre son propre système de sauvegarde, l'utilisation de Git reste la solution optimale pour la gestion de vos fichiers de données.

Contexte & rédaction

Un contexte explicite peut résider dans le nom de la clé, son chemin d'accès (hiérarchie), son voisinage (clés parentes/enfants) ou ses métadonnées.
Évitez les clés ambiguës qui laissent place à la spéculation.
Si la lecture d'une clé nécessite de vérifier son utilité dans le code, c'est que l'architecture de vos données doit être améliorée.

Exemples de clés explicites :
game:.scenes.001.events.001.1
game:.scenes.001.events.001.2
game:.scenes.the-ice-land.events.the-lost-house.1
game:.scenes.the-ice-land.events.the-lost-house.2
game:.ui.menus.new-game.label
game:.ui.menus.new-game.description

Ces clés permettent de comprendre immédiatement qu'elles pointent vers des dialogues ou des éléments d'interface.

Exemples de mauvaises pratiques :
game:events.001.1 (Trop vague : où cet événement est-il utilisé ?)
game:.scenes-events-the-lost-house.1 (Redondance dans le chemin)
game:.ui-menus.new-game-label (Concaténation inutile)

Évitez la redondance dans les chemins.
Si vous avez besoin de faciliter la recherche, exportez plutôt un fichier de types contenant les clés concaténées plutôt que de dégrader la structure de vos données JSON.

Une chaîne ne doit jamais dépendre d’un élément externe pour être comprise (position à l’écran, couleur, icône).
Ex. : évitez
"Cliquez ici pour continuer"
Préférez
"Continuer vers le paiement"
Le texte doit rester compréhensible même extrait de son interface utilisateur (UI).
Certaines langues peuvent ne pas avoir de traduction possible ou peuvent avoir des formulations différentes selon l'action et l'emplacement du texte.

Les textes d’action doivent décrire l’action et l’objet : « Aller au paiement », « Télécharger le rapport PDF » et non « Cliquez ici » ou « En savoir plus » sans précision.

Ne transposez pas les principes de programmation (comme S.O.L.I.D.) à la rédaction de contenu i18n.
La rédaction et le code sont des disciplines différentes.
Privilégiez des phrases complètes plutôt que des fragments, car chaque langue possède sa propre syntaxe.
Bien que des frameworks comme `i18next` supportent l'imbrication (« nesting »), cela génère souvent une complexité inutile.
Si une variation est nécessaire, réécrivez la phrase intégralement.
Limitez l'interpolation à des variables simples comme des noms ou des nombres.

Si l'interface impose une limite de caractères ou une contrainte de longueur, précisez-le dans les métadonnées et fournissez un visuel (capture d'écran ou maquette).
Il est plus simple pour un traducteur d'adapter son texte à une interface restrictive que pour un programmeur de rendre l'UI dynamique pour toutes les langues du monde.
Déléguer cette gestion au rédacteur garantit une meilleure expérience utilisateur (UX).

N'insérez pas de caractères spéciaux ou d'emojis directement dans vos textes.
Passez par des variables (ex. : <t title=) afin de contrôler leur rendu via le code.
Le rendu des emojis varie considérablement selon le système d'exploitation et l'environnement de l'utilisateur.

Les expressions idiomatiques, jeux de mots et métaphores locales sont à proscrire dans les chaînes génériques.
Ce qui est clair dans une langue peut devenir absurde ou intraduisible dans une autre.

Rédigez comme si le traducteur n’avait accès ni au code ni à l’UI.
Tout ce qui est nécessaire à la compréhension doit être présent dans la clé, sa hiérarchie ou ses métadonnées.

Technique I18n

Privilégiez les placeholders nommés (`{username}`, `{count}`) aux index positionnels (`{0}`, `{1}`). LSDE propose une section dédiée aux variables pour définir leur contexte et assurer leur traçabilité au sein de votre projet.

Chaque placeholder doit être atomique et représenter une donnée unique (nom, date, nombre). Évitez les variables génériques ou polymorphes qui compliquent la traduction et l'interprétation.

Anticipez l'affichage pour les langues s'écrivant de droite à gauche.
Le rendu doit rester fluide et structurellement correct sans nécessiter de modifications manuelles de la chaîne de caractères.

Ne composez jamais une phrase en combinant plusieurs clés de traduction.
Pour respecter les syntaxes et les accords grammaticaux propres à chaque langue, toute phrase complète doit correspondre à une clé unique.