Nachrichten und Kontext
Schreibe vollständige Ausgangsnachrichten, erläutere ihre Bedeutung und füge variable Werte ein, ohne die Identität der Nachrichten zu ändern.
Eine übersetzte Nachricht braucht genügend Informationen, damit die beabsichtigte Handlung oder Bedeutung erhalten bleibt. Schreibe den vollständigen Ausgangstext und erläutere seine Verwendung in context. Übergib Namen, Anzahlen und andere variable Daten über values.
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>
);
}Das Ergebnis ist eine Zeichenfolge. TextOptions erfordert context: string und akzeptiert values?: Record<string, string | number>. Der Katalog enthält die Satzvorlage; in einer Übersetzung lässt sich {name} an die Stelle verschieben, die die jeweilige Grammatik erfordert.
Erkläre, was eine mehrdeutige Nachricht bedeutet #
„Save“ kann das Absenden eines Formulars oder das Speichern eines Artikels als Lesezeichen bedeuten. Durch den Kontext werden daraus zwei unterschiedliche Nachrichten, obwohl ihr englischer Ausgangstext identisch ist:
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");Die Schlüssel unterscheiden sich. So können Übersetzende für jede Handlung das passende Verb wählen. Ein Kontext wie „Text, der Nutzern angezeigt wird“ löst diese Mehrdeutigkeit nicht auf. Beschreibe die Handlung, die Zielgruppe oder eine Einschränkung, die sich auf die Formulierung auswirken könnte.
Der Extraktor schreibt diese Informationen in den @context-Kommentar des Katalogs. Sie dienen als Hinweise für die Übersetzung und erscheinen nicht als Text in der Benutzeroberfläche. Hinterlege wiederkehrende Terminologie, Anweisungen und Vorgaben zum Sprachstil im Übersetzungskontext der Lokalisierungs-Engine. Die Bedeutung der einzelnen Nachricht bleibt dagegen direkt beim Aufruf.
Identität einer Nachricht #
computeKey(source: string, context?: string): string erzeugt aus dem Ausgangstext und dem Kontext einen Schlüssel mit acht Zeichen. Ein nicht leerer Kontext wird mit einem Nullzeichen als Trennzeichen mit dem Ausgangstext verbunden. Die kombinierte Eingabe wird in die Unicode-Normalform NFC gebracht, anschließend wird aus ihren UTF-8-Bytes ein Hash berechnet.
Kanonisch äquivalente Unicode-Schreibweisen erhalten denselben Schlüssel. Änderungen an Formulierung, Zeichensetzung, Groß- und Kleinschreibung, Leerraum oder Kontext können einen neuen Schlüssel erzeugen. Werte fließen nicht in den Hash ein. Deshalb verwendet jeder Name in der Begrüßung denselben Nachrichteneintrag.
Führe nach einer Änderung am Ausgangstext oder Kontext die Extraktion erneut aus und sieh dir die neuen und verwaisten Einträge an. Wenn du eine Übersetzung unter den neuen Schlüssel kopierst, ohne ihre Bedeutung zu kontrollieren, kann genau die Formulierung erhalten bleiben, die mit der Änderung des Ausgangstextes ersetzt werden sollte. Der Wertebereich von Hashes ist begrenzt; der Extraktor erkennt Kollisionen zwischen den Nachrichten, die er erfasst.
Gestalte Aufrufe so, dass sie extrahierbar bleiben #
Verwende in Aufrufen wie l.text(...) Zeichenfolgenliterale für Ausgangstext und Kontext. Die Laufzeitumgebung kann eine berechnete Zeichenfolge entgegennehmen, aber der Extraktor kann nicht jede Zeichenfolge ableiten, die das Programm möglicherweise erzeugt. Verwende als Empfänger l oder eine unterstützte Variable, die aus useLingo oder createLingo erstellt wurde. Die Referenz zur Extraktion beschreibt die erkannten Formen.
Verwende Platzhalter für variable Daten, statt Ausgangszeichenfolgen wie "Welcome, " + name zu erzeugen. Eine stabile Vorlage lässt sich extrahieren, einmal pro Bedeutung übersetzen und für jeden Wert wiederverwenden.
Interpolation und ICU #
Einfache Platzhalter verwenden Namen wie {name}. Übergebene Werte werden zu Text. Einfache Platzhalter ohne übergebenen Wert bleiben sichtbar. Lässt du das values-Objekt weg, wird die ausgewählte Vorlage ohne Interpolation zurückgegeben.
Für grammatische Formen, die von einer Anzahl oder Kategorie abhängen, unterstützt der Textformatierer über intl-messageformat komplexe ICU-Muster:
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 },
});Damit wird No files zurückgegeben. Der explizite =0-Zweig unterscheidet die Zahl 0 von den üblichen Pluralkategorien der Sprache. Übergib alle Argumente, die die ausgewählte Vorlage benötigt. Schlägt das Parsen oder Formatieren komplexer ICU-Muster fehl, gibt die Laufzeitumgebung diese Vorlage zurück und meldet einen Entwicklungsfehler, wobei doppelte Meldungen unterdrückt werden. Sie ersetzt eine fehlerhafte Übersetzung nicht durch einen neu formatierten Ausgangstext.
Plural- und Auswahlformen bietet Hilfsfunktionen für vollständige Alternativen. Rich Text fügt React-Elemente über einen separaten Parser für benannte Tags ein. Verwende die passende Form, statt komplexe ICU-Ausdrücke in Rich-Text-Vorlagen zu mischen.