Interaktive Rich-Text-Nachrichten lokalisieren
Übersetze vollständige Sätze, während der React-Code die Kontrolle über Links, Komponenten und Werte behält.
„Lies die Richtlinie, bevor du fortfährst“ ist ein vollständiger Satz – auch wenn „Richtlinie“ ein Link ist. Übersetzt du ihn als Ganzes, kann der Link in einer anderen Sprache an die passende Stelle rücken. Die Kontrolle über sein Ziel bleibt dabei im Anwendungscode.
Die Methode rich des React-Pakets bildet diesen Link als benannten Slot ab. Der Katalog liefert den Satz, ein React-Renderer die Komponente für diesen Slot.
Einen vollständigen Satz mit Link rendern #
Installiere @lingo.dev/react in einer bestehenden React-19-Anwendung. Dieses lokale Beispiel verwendet einen beispielhaften spanischen Katalog und kommt ohne Übersetzungsanfrage aus:
npm install @lingo.dev/reactimport { computeKey, LingoProvider, useLingo } from "@lingo.dev/react";
const messages = {
[computeKey(
"Read the <policy>policy</policy> before continuing.",
"Notice before account creation",
)]: "Antes de continuar, lee la <policy>política</policy>.",
};
function ConsentNotice() {
const l = useLingo();
return (
<p>
{l.rich("Read the <policy>policy</policy> before continuing.", {
context: "Notice before account creation",
tags: {
policy: (children) => <a href="/policy">{children}</a>,
},
})}
</p>
);
}
export function App() {
return (
<LingoProvider locale="es" messages={messages}>
<ConsentNotice />
</LingoProvider>
);
}Der Absatz sollte die spanische Entsprechung von „Bevor du fortfährst, lies die Richtlinie.“ anzeigen. Im übersetzten Satz steht der Verweis auf die Richtlinie an einer anderen Stelle, während der Link weiterhin auf /policy zeigt. Der als Literal angegebene Quelltext und der Kontext im Aufruf sorgen außerdem dafür, dass die Nachricht bei der Extraktion erkannt wird. computeKey erzeugt die tatsächliche Identität der Testdaten, statt einen erfundenen Hash zu verwenden.
Der Provider verwendet derzeit die Kontextsyntax von React 19, obwohl das Paket React 18/19 als Peer-Abhängigkeiten deklariert. Überprüfe die Kompatibilität mit React 18 separat. Der React-Schnellstart erklärt, wie du den Provider einrichtest und den ersten Katalog anlegst.
Werte und Verhalten im Code belassen #
Der Name policy bezeichnet einen Slot, kein HTML-Element aus der Übersetzung. Der zugehörige Renderer steuert das Ziel und das Verhalten. Ermittle sprachspezifische Ziele im Code anhand einer bekannten Routenzuordnung. Ereignishandler und beliebige HTML-Attribute gehören nicht in den Katalog.
Verwende für veränderliche Werte benannte Platzhalter:
const greeting = l.text("Welcome, {name}", {
context: "Greeting on the signed-in account page",
values: { name },
});
const countLabel = l.plural(
count,
{ one: "# item", other: "# items" },
{ context: "Number of items in the cart" },
);
const roleLabel = l.select(
role,
{ admin: "Administrator", other: "Member" },
{ context: "Account role label" },
);Diese Aufrufe gehören in eine Komponente mit const l = useLingo() und Anwendungswerten für name, count und role. text gibt reinen Text zurück, plural bestimmt die passende Grammatik anhand der Anzahl, und select wählt anhand eines exakten Selektors aus, mit other als Rückfalloption. Die Rich-Text-Verarbeitung unterstützt benannte Tags und einfache Wertinterpolation, verwendet aber nicht den komplexen ICU-Formatierer der Textverarbeitung. Nutze Pluralformen, Datumsangaben und Zahlen für diese Entscheidungen zur Laufzeit.
Halte den Quelltext statisch. Wenn du den Namen einer Person in die Quellzeichenfolge einfügst, entsteht für jede Person ein anderer Quelltext. Das verhindert eine zuverlässige Extraktion. Der Kontext sollte den Verwendungszweck beschreiben, etwa „Bezeichnung der Kontorolle“, denn Quelltext und Kontext bestimmen gemeinsam die Identität. Ändere den Kontext nur bewusst, sobald Übersetzungen vorliegen.
Die lokalen Testdaten durch extrahierte Kataloge ersetzen #
Wenn die aktuelle CLI installiert ist, führe Folgendes aus:
lingo extract --src src --source-locale enOhne abweichende Pfadangaben werden dabei locales/en.jsonc und lingo.d.ts geschrieben. Sieh dir den extrahierten Quelltext, den Kontext und den Schlüssel an. Nimm die Deklaration in die TypeScript-Konfiguration der Anwendung auf. Die Extraktion unterstützt erkennbare Nachrichtenaufrufe, erfasst aber keine beliebigen dynamisch erzeugten Quellzeichenfolgen.
Folge dem CLI-Schnellstart, um dich zu authentifizieren und eine Lokalisierungs-Engine zu verknüpfen. Wähle anschließend in .lingo/config.json diese konkrete locales/en.jsonc-Quelle und die benötigten Zielsprachen aus. Übersetze den Katalog über diesen dateibasierten Workflow und rufe ihn darüber ab. Nutze die Anleitung zum Laden von Katalogen, um JSONC zu parsen, aktive Schlüssel aus der passenden Quellrevision auszuwählen und dem Provider die Zielzeichenfolgen bereitzustellen. Der allgemeine Dateiübersetzer übernimmt Kommentare aus dem Quellkatalog nicht in die Zielausgabe.
Lade denselben Hinweis mit dem abgerufenen spanischen Katalog. Bei fehlenden oder leeren Einträgen wird auf den Quelltext zurückgegriffen. Vergleiche deshalb nicht nur die sichtbare Ausgabe, sondern auch die erforderlichen Zielschlüssel.
Interaktion und fehlerhafte Fälle testen #
Öffne den Link zur Richtlinie mit der Tastatur und kontrolliere seinen barrierefreien Namen. Lies auch die Zeichensetzung rund um den Link, nachdem er verschoben wurde. Eine vollständige Übersetzung muss sowohl die Bedeutung des Satzes als auch die Handlungsmöglichkeit für die Lesenden erhalten.
Entferne in einem lokalen Testkatalog den Tag-Handler, füge ein unbekanntes Tag ein und lasse ein Tag offen. Der aktuelle Renderer gibt unbekanntes Markup oder Markup ohne passendes Gegenstück als Text aus. Bei verschachtelten Tags mit gleichem Namen ist die Paarbildung nur eingeschränkt möglich. Er ist weder ein Renderer für beliebiges HTML noch ein Validator, der jede fehlerhafte Nachricht zurückweist.
Teste bei reinem Text fehlende Werte und fehlerhafte komplexe ICU-Nachrichten: Nicht aufgelöste Platzhalter oder die unformatierte Vorlage können sichtbar bleiben, begleitet von Diagnosemeldungen während der Entwicklung. Teste bei Nachrichten zu Anzahl und Rolle die Pluralkategorien der Zielsprache sowie eine unbekannte Rolle. In der Rich-Text-Referenz und der React-Testanleitung findest du das genaue Verhalten für diese Tests.