Vérifier les types des appels de messages

Générez et incluez des déclarations qui vérifient les chaînes source, les contextes et les valeurs des messages à mesure que vous modifiez le code.

Un appel de message peut être valide en TypeScript tout en demandant la mauvaise entrée du catalogue. Un contexte modifié ou une variable mal orthographiée peut laisser le texte source ou {name} à l'écran. L'extraction génère des déclarations qui intègrent les messages source connus au système de types de l'application.

Générer la déclaration et l'inclure #

Une fois la CLI installée, exécutez :

sh
npx lingo extract --src src --source-locale en

Les fichiers de sortie par défaut sont locales/en.jsonc et lingo.d.ts. Ajoutez lingo.d.ts à la liste d'inclusion tsconfig existante de l'application si aucun des motifs actuels ne le couvre. Conservez les autres entrées :

json
{
  "include": ["src", "lingo.d.ts"]
}

Exécutez la vérification des types habituelle de l'application. Une déclaration située hors du projet du compilateur n'impose aucune contrainte aux appels. Si l'extraction utilise --types ou i18n.typesPath, incluez plutôt le chemin de sortie correspondant.

Comprendre l'interface générée #

Le fichier enrichit LingoMessages avec les chaînes source et leurs options. Voici un exemple de la structure générée :

ts
export {};

declare module "@lingo.dev/react" {
  interface LingoMessages {
    "Hello, {name}.": {
      values: { name: string | number };
      context: "Greeting on the account dashboard";
    };
    "Save": {
      context: "Submit settings" | "Bookmark an article";
    };
  }
}

Régénérez ce fichier plutôt que de tenir cet exemple à jour à la main. Le message de salutation nécessite désormais values.name et son contexte extrait. Save accepte l'un ou l'autre des contextes enregistrés. Une chaîne source non répertoriée ne satisfait pas la contrainte MessageKey.

Sans entrées générées, LingoMessages est vide et MessageKey autorise n'importe quelle chaîne. Une fois les entrées ajoutées, MessageKey devient l'union de ses clés de type chaîne. Le comportement à l'exécution reste inchangé : ces contraintes s'appliquent à l.text et l.rich uniquement pendant l'édition du code.

Garder les types à jour avec la source #

Relancez l'extraction après toute modification du texte, du contexte ou des variables. Les messages supprimés deviennent orphelins et sont exclus de la génération. Les entrées sans contexte ne produisent aucune signature générée, sauf si une autre entrée active pour la même chaîne source fournit un contexte. Plusieurs contextes pour une même chaîne source forment une union.

Pour vérifier que les fichiers sont à jour sans écrire de fichiers :

sh
npx lingo extract --src src --source-locale en --check

Cette opération compare le JSONC et les déclarations au résultat de l'extraction actuelle. Il s'agit d'une vérification locale, pas d'une demande de traduction. Exécutez-la en complément de la vérification des types pour éviter qu'une ancienne déclaration ne définisse, sans que vous le sachiez, un inventaire de messages obsolète.

Types des valeurs et couverture #

Le générateur reconnaît les arguments ICU de premier niveau. Il utilise number pour les arguments de pluriel, d'ordinal et de nombre ; string pour les arguments de sélection ; Date | number pour les arguments de date et d'heure ; et string | number pour les variables simples. Il ne détecte pas toutes les variables imbriquées dans une branche de pluriel : testez donc explicitement les valeurs de ces branches.

Les contraintes générées sur les chaînes source s'appliquent à text et rich. Les fonctions utilitaires plural et select conservent leurs propres signatures pour les formes et les options. Les appels de texte enrichi ajoutent une table de balises facultative, mais les déclarations ne vérifient pas l'emplacement des balises dans la traduction cible.

Les types indiquent si un appel respecte le contrat extrait de la source. Les tests de rendu indiquent si la traduction chargée peut utiliser ces valeurs. Gardez les deux : même un appel valide peut recevoir une entrée de catalogue manquante ou une traduction cible dont la syntaxe ICU est incorrecte.