Messages et contexte

Rédigez des messages sources complets, expliquez leur sens et insérez des valeurs variables sans changer leur identité.

Pour préserver l'action ou le sens exprimé, un message traduit doit s'appuyer sur suffisamment d'informations. Rédigez le texte source complet et expliquez son utilisation dans context. Fournissez les noms, les nombres et les autres données variables via values.

tsx
import { useLingo } from "@lingo.dev/react";

export function Greeting({ name }: { name: string }) {
  const l = useLingo();
  return (
    <h1>
      {l.text("Welcome back, {name}.", {
        context: "Greeting at the top of the account dashboard",
        values: { name },
      })}
    </h1>
  );
}

Le résultat est une chaîne de caractères. TextOptions nécessite context: string et accepte values?: Record<string, string | number>. Le catalogue contient le modèle de phrase ; la traduction peut déplacer {name} à l'endroit requis par la grammaire de la langue cible.

Expliquez le sens d'un message ambigu #

« Enregistrer » peut désigner l'envoi d'un formulaire ou l'ajout d'un article aux favoris. Le contexte en fait deux messages distincts, même si leur texte source anglais est identique :

ts
import { computeKey } from "@lingo.dev/react";

const submitKey = computeKey("Save", "Submit changes to account settings");
const bookmarkKey = computeKey("Save", "Bookmark this article for later reading");

Les clés sont différentes. La personne chargée de la traduction peut ainsi choisir le verbe adapté à chaque action. Un contexte comme « Texte affiché à un utilisateur » ne lève pas cette ambiguïté ; décrivez l'action, le public ou la contrainte susceptible de modifier la formulation.

L'extracteur inscrit ces informations dans le commentaire @context du catalogue. Elles servent à guider la traduction et ne sont pas affichées dans l'interface. Placez la terminologie récurrente, les instructions et les exigences de ton dans le contexte de traduction du moteur de localisation, et conservez le sens propre à chaque message dans l'appel.

Identité du message #

computeKey(source: string, context?: string): string génère une clé de huit caractères à partir du texte source et du contexte. Il associe tout contexte non vide au texte source avec un caractère nul comme séparateur, normalise l'ensemble en Unicode NFC, puis calcule le hachage de ses octets UTF-8.

Les formes Unicode canoniquement équivalentes partagent la même clé. Modifier la formulation, la ponctuation, la casse, les espaces ou le contexte peut générer une nouvelle clé. Les valeurs n'entrent pas dans le calcul du hachage : tous les noms insérés dans le message de salutation utilisent donc la même entrée du catalogue.

Après avoir modifié le texte source ou le contexte, relancez l'extraction et examinez les nouvelles entrées ainsi que les entrées orphelines. Copier une traduction sous la nouvelle clé sans en vérifier le sens risque de conserver précisément la formulation que la modification du texte source visait à remplacer. Le nombre de valeurs de hachage possibles est limité ; l'extracteur détecte les collisions entre les messages qu'il collecte.

Gardez les appels extractibles #

Dans les appels tels que l.text(...), utilisez des chaînes sources et un contexte définis sous forme de littéraux. Le système d'exécution peut recevoir une chaîne calculée, mais l'extracteur ne peut pas déduire toutes les chaînes que le programme pourrait construire. Gardez l comme receveur, ou utilisez une variable prise en charge créée à partir de useLingo ou de createLingo. La référence de l'extraction décrit les formes reconnues.

Utilisez des paramètres de substitution pour les données variables plutôt que de générer des chaînes sources telles que "Welcome, " + name. Un modèle stable peut être extrait, traduit une seule fois par sens, puis réutilisé pour chaque valeur.

Interpolation et ICU #

Les paramètres de substitution simples portent des noms tels que {name}. Les valeurs fournies sont converties en texte. Les paramètres simples dont la valeur manque restent visibles. Si vous omettez l'objet values, le modèle sélectionné est renvoyé sans interpolation.

Lorsque la grammaire dépend d'une quantité ou d'une catégorie, le formateur de texte prend en charge des modèles ICU complexes via intl-messageformat :

ts
import { createLingo } from "@lingo.dev/react";

const l = createLingo("en");
const label = l.text("{count, plural, =0 {No files} one {# file} other {# files}}", {
  context: "Number of files attached to a message",
  values: { count: 0 },
});

Cela renvoie No files. La branche explicite =0 distingue zéro des catégories de pluriel habituelles de la langue. Fournissez tous les arguments nécessaires au modèle sélectionné. Si l'analyse ou le formatage d'un modèle ICU complexe échoue, le système d'exécution renvoie ce modèle et signale une erreur de développement dédupliquée ; il ne remplace pas une traduction mal formée par une version du texte source qu'il vient de formater.

Pluriels et sélections propose des fonctions utilitaires pour des variantes complètes. Texte enrichi insère des éléments React à l'aide d'un analyseur distinct de balises nommées. Utilisez la forme adaptée plutôt que de mêler des expressions ICU complexes à des modèles de texte enrichi.