Extraire et charger des catalogues de messages
Extrayez les messages sources, récupérez un fichier JSONC traduit et créez une table utilisable à l’exécution à partir des métadonnées sources correspondantes.
Un composant contient le message source et son contexte. L’extraction rassemble ces appels dans un fichier à traduire. Le chargement associe ensuite les valeurs traduites aux clés du composant. Ce guide suit la première salutation tout au long de ce workflow de fichiers pour produire la table Messages nécessaire au fournisseur.
Extraire la source #
Installez la CLI et les dépendances du chargeur dans l’application :
npm install --save-dev @lingo.dev/cli@latest
npm install @lingo.dev/spec@1.17.1 jsonc-parser
npx lingo extract --src src --source-locale enL’extraction s’exécute localement, sans clé API. Par défaut, elle écrit locales/en.jsonc et lingo.d.ts. Les options explicites --out et --types ont priorité sur les valeurs configurées i18n.messagesPath et i18n.typesPath, qui ont elles-mêmes priorité sur les valeurs par défaut. Une application Pages dont les appels se trouvent en dehors de src utilise le répertoire où ils se trouvent, par exemple --src pages.
Examinez l’entrée de la salutation. Sa valeur contient le modèle anglais complet ; sa clé est issue de la source et du contexte. Les commentaires qui la précèdent indiquent @context pour le sens, @src pour l’emplacement dans la source et @orphan lorsqu’une entrée précédemment extraite n’est plus active. Relisez ces modifications avant de demander des traductions.
Traduire le catalogue sélectionné #
Pour une application sans configuration Lingo.dev, initialisez ce fichier précis avec l’espagnol comme langue cible, puis authentifiez-vous et associez un moteur de localisation :
npx lingo init --source en --targets es --files 'locales/en.jsonc' --yes
npx lingo login
npx lingo linkVous devez avoir accès à un moteur de localisation activé et disposer d’un quota d’utilisation suffisant sur votre compte. La section Authentification de la CLI détaille les identifiants nécessaires aux exécutions sans intervention.
Si .lingo/config.json existe déjà, conservez son association et les autres entrées de fichiers. Ajoutez ou mettez à jour l’entrée qui sélectionne locales/en.jsonc et vérifiez que la langue source du projet est en. Si vous disposez déjà d’une version de référence, terminez les mises à jour habituelles des langues cibles existantes avec npx lingo push --wait, traitez toute relecture en attente ou tout échec, puis examinez les modifications récupérées avant d’ajouter es à targetLocales. Conservez la même révision source pendant le remplissage rétroactif qui suit. La section Ajouter une langue explique cet ordre de procéder. N’utilisez pas init --force pour modifier la configuration : cette commande reconstruit les entrées de fichiers et peut supprimer des options avancées. La section Configuration décrit la structure complète.
Pour un nouveau projet, ou une fois cette préparation terminée pour un projet existant, demandez les fichiers cibles manquants et attendez leur récupération. Ne modifiez pas les fichiers cibles pendant cette attente : le téléchargement effectué par la commande peut écraser vos modifications locales.
npx lingo push --backfill-missing --waitUne fois l’exécution terminée, examinez locales/es.jsonc. Traitez tout état de relecture ou d’échec signalé avant de considérer le résultat comme complet. Pour les modifications ultérieures de la source, relancez l’extraction et utilisez npx lingo push --wait ; le remplissage rétroactif sert à récupérer les fichiers manquants, pas à effectuer les mises à jour habituelles d’une cible existante.
Conserver les métadonnées sources avec la révision cible #
Le workflow général de traduction JSONC conserve les marqueurs @orphan de la source dans la cible, mais supprime ses commentaires @context et @src. Le fichier cible seul ne permet pas au chargeur de déterminer à quelle page un message appartenait.
Conservez le fichier source extrait correspondant à la même révision que la cible. Sélectionnez les entrées actives de cette source et associez leurs clés aux valeurs traduites de la cible. Vous excluez ainsi les messages supprimés tout en conservant la possibilité de sélectionner les entrées par route source. Les clés absentes de la cible restent absentes, ce qui permet d’utiliser la source comme solution de repli à l’exécution.
Analyser un catalogue brut #
Créez src/catalog.ts avec ce chargeur propre à l’application :
import { parse, type ParseError } from "jsonc-parser";
import { getActiveEntries, readLocaleFile, type LocaleEntry } from "@lingo.dev/spec";
import type { Messages } from "@lingo.dev/react";
function readStringCatalog(raw: string) {
const errors: ParseError[] = [];
const value: unknown = parse(raw, errors, { allowTrailingComma: true });
if (
errors.length > 0 ||
value === null ||
typeof value !== "object" ||
Array.isArray(value) ||
Object.values(value).some((entry) => typeof entry !== "string")
) {
throw new Error("Expected a flat JSONC object with string values");
}
return readLocaleFile(raw);
}
export function loadMatchedMessages(
sourceJsonc: string,
targetJsonc: string,
include: (entry: LocaleEntry) => boolean = () => true,
): Messages {
const active = getActiveEntries(readStringCatalog(sourceJsonc).entries);
const target = new Map(readStringCatalog(targetJsonc).entries.map((entry) => [entry.key, entry.value]));
return Object.fromEntries(
active.filter(include).flatMap((entry) => {
const value = target.get(entry.key);
return value === undefined ? [] : [[entry.key, value]];
}),
);
}readLocaleFile analyse la syntaxe JSONC et les métadonnées, mais ne valide pas la structure à l’exécution. Malgré le type d’entrée déclaré, il accepte les tableaux et les valeurs autres que des chaînes, et ne renvoie aucune entrée lorsque la racine est une valeur primitive ou nulle. La première fonction ci-dessus rejette ces structures avant que les valeurs n’atteignent le moteur de rendu. Les deux fonctions sont locales et n’effectuent aucune E/S.
Dans une application Vite, chargez les fichiers sous forme de texte brut dans le module qui alimente le fournisseur :
import source from "../locales/en.jsonc?raw";
import target from "../locales/es.jsonc?raw";
import { loadMatchedMessages } from "./catalog";
export const spanishMessages = loadMatchedMessages(source, target);Cela suppose que le module se trouve directement sous src et que les types client de Vite sont inclus. Transmettez spanishMessages comme messages avec locale="es". La salutation devrait désormais utiliser le modèle espagnol récupéré tout en continuant à remplacer {name} par Ana. Vérifiez la formulation obtenue et testez les entrées manquantes : charger un fichier et évaluer sa qualité linguistique sont deux opérations distinctes.
Sélectionner uniquement les entrées sources nécessaires à une route #
Le prédicat facultatif include s’exécute sur les entrées sources actives avant la jointure. Un chargeur de page peut utiliser entry.metadata.src pour inclure ses propres appels et les composants partagés. Effectuez cette sélection sur la source, où les métadonnées sont encore présentes. Conservez la source et la cible ensemble lors du déploiement pour éviter que la sélection par route utilise les clés d’une autre révision.
Le guide Next Pages fournit un prédicat de route complet. Le guide TanStack utilise ce chargeur pour le catalogue associé à sa requête. Leurs chargeurs intégrés peuvent filtrer les fichiers contenant des métadonnées, mais aucun n’associe automatiquement les cibles sans commentaires aux métadonnées sources.
Référence des utilitaires de spécification #
| Export | Contrat |
|---|---|
readLocaleFile(content): LocaleFile | Analyse le JSONC, y compris les virgules finales, ainsi que les commentaires de métadonnées en bloc qui précèdent les entrées ; toute erreur de syntaxe déclenche une exception. |
getActiveEntries(entries): LocaleEntry[] | Conserve les entrées dont metadata.orphan n’est pas évalué comme vrai. |
LocaleFile | { entries: LocaleEntry[] }. |
LocaleEntry | { key: string; value: string; metadata: EntryMetadata }. |
EntryMetadata | context, src et orphan facultatifs. |
computeKey(source, context?) | Identité source/contexte normalisée et partagée, également exportée par React. |
buildIcuPlural(forms) | Produit les catégories cardinales connues dans l’ordre canonique. |
buildIcuSelect(forms) | Produit les alternatives avec des clés triées. |
Les générateurs ICU acceptent des objets de chaînes ; les types React de pluriel et de sélection ajoutent leur forme obligatoire other. Le catalogue obtenu pour l’exécution est une simple table Messages, et non un LocaleFile.
Les ressources existantes organisées par clés, les documents et les modules TypeScript statiques par langue utilisent leurs propres gestionnaires de format plutôt que la méthode d’extraction de ce guide. Les projets d’exemple présentent ces structures aux côtés d’applications React.