Fehler bei React-Nachrichten beheben
Finde heraus, an welcher Stelle zwischen Extraktion und Rendering eine Nachricht ihre Übersetzung, Werte, Tags oder Sprache verliert.
Verfolge die Nachricht, die tatsächlich auf dem Bildschirm erscheint. Quelltext und Kontext bestimmen ihren Schlüssel; der nächstgelegene Provider liefert den Katalog; die ausgewählte Vorlage wird mit den Werten des Aufrufs formatiert. Anhand dieser Eingaben lässt sich der Fehler meist finden, ohne generierte Schlüssel von Hand zu ändern.
useLingo löst außerhalb eines Providers einen Fehler aus #
Platziere LingoProvider oberhalb der Komponente, die den Hook aufruft – auch in Tests und isolierten Vorschauen. Ein Provider, den dieselbe Komponente zurückgibt, liegt unterhalb dieses Hooks. Verschiebe den Hook in eine untergeordnete Komponente oder verwende createLingo(locale, messages) in einer Funktion, die nicht über den React-Kontext rendert.
Verwende React 19 für die aktuelle Provider-Implementierung. Auch wenn das Paket einen breiteren Versionsbereich für seine Peer-Abhängigkeiten angibt, ist die verwendete React-19-Kurzschreibweise für den Kontext nicht mit React 18 kompatibel.
Quelltext erscheint statt einer Übersetzung #
- Sieh dir die tatsächlichen Werte von
localeundmessagesdes nächstgelegenen Providers an. Die Nachrichten müssen als Zuordnung von Hashes zu Zeichenfolgen vorliegen, nicht als Datei-URL, Promise oderLocaleFile. - Berechne
computeKey(source, context)anhand des exakten Aufrufs. Suche diesen Schlüssel in der bereitgestellten Zuordnung. Änderungen an Satzzeichen, Leerraum oder Kontext können eine neue Identität erzeugen. - Wenn der Schlüssel bei der Extraktion fehlt, gib Quelltext und Kontext als Literale an und verwende einen unterstützten Empfänger wie
l.text(...). Führe dann die Extraktion erneut aus. Ein dynamisch berechneter Aufruf kann zur Laufzeit gerendert werden, ohne extrahierbar zu sein. - Wenn der Quellkatalog den Schlüssel enthält, der Zielkatalog aber nicht, rufe die fertige Übersetzung ab und lade die Zuordnung neu. Das Einreichen allein sorgt noch nicht dafür, dass die Datei in der Anwendung verfügbar ist.
- Wenn die Datei den Schlüssel enthält, der Provider aber nicht, untersuche die Pfade des Loaders und die Routenauswahl. Kataloge laden zeigt, wie die Daten anhand der Quellschlüssel zusammengeführt werden müssen, wenn übersetztes JSONC seine Metadaten verloren hat.
Sowohl bei fehlenden Werten als auch bei leeren Zeichenfolgen wird auf den Quelltext zurückgegriffen. Warnungen im Entwicklungsmodus unterscheiden die beiden Fälle und werden pro Schlüssel und Sprache nur einmal ausgegeben. Im Produktionsmodus werden diese Diagnosemeldungen unterdrückt. Eine leere Konsole ist daher kein Nachweis dafür, dass der Katalog vollständig ist.
Der Next-Loader gibt bei einer fehlenden Datei {} zurück, kann bei fehlerhaftem JSONC jedoch einen Fehler auslösen. Der integrierte Katalog von TanStack fängt Fehler durch fehlende Dateien sowie Lade- und Parsing-Fehler ab, gibt dafür {} zurück und speichert dieses Ergebnis im Cache. In beiden Fällen kann der Rückgriff auf den Quelltext die Seite lesbar halten und zugleich ein Ladeproblem verbergen.
Ein Platzhalter oder ICU-Ausdruck bleibt sichtbar #
Kontrolliere das values-Objekt, das beim Aufruf ankommt. Fehlen einfache Werte, bleibt {name} sichtbar. Ohne Werteobjekt gibt die Laufzeit die ausgewählte Vorlage unformatiert zurück.
Untersuche bei einer komplexen ICU-Nachricht die Syntax, Argumentnamen und Werttypen der ausgewählten Zielvorlage. Bei einem Parsing- oder Formatierungsfehler wird genau diese Vorlage zurückgegeben. Im Entwicklungsmodus wird außerdem eine Fehlermeldung ausgegeben, die bei Wiederholung unterdrückt wird. Deshalb kann eine fehlerhafte Übersetzung statt des englischen Quelltexts erscheinen. Korrigiere die Vorlage oder übergib das fehlende Argument und rendere den Fall erneut.
Generierte Deklarationen erfassen die erkannten Argumente des Quelltexts. Sie validieren jedoch weder die Zielsyntax noch erkennen sie jeden Platzhalter, der innerhalb eines ICU-Zweigs verschachtelt ist. Teste den betroffenen Zweig mit echten Werten.
Ein Link verschwindet oder Tags erscheinen als Text #
Rich-Text-Nachrichten verwenden benannte Callbacks wie tags.link. Der Name muss exakt mit dem übersetzten Tag-Namen übereinstimmen, und das Linkziel muss im Callback bleiben. Unbekannte Tag-Paare, selbstschließende Tags und öffnende Tags ohne schließendes Gegenstück bleiben als wörtlicher Text erhalten.
Verwende unterschiedliche Namen für verschachtelte Elemente. Wiederholte Verschachtelungen mit demselben Namen unterstützt der Parser nicht. Rich-Text-Nachrichten unterstützen einfache Platzhalter, aber nicht die vollständige ICU-Grammatik; verwende dafür die Hilfsfunktionen für Textgrammatik. Rich-Text zeigt die unterstützten Formen.
Die URL ändert sich, die Sprache aber nicht #
Ersetze Sprache und Katalog gemeinsam. Wenn du nur die Sprache aktualisierst, kann französischer Text nach spanischen Regeln formatiert werden. Achte auch auf verschachtelte Provider: Ein untergeordneter Provider mit einer anderen Sprache ist unabhängig und übernimmt den Katalog des übergeordneten Providers nicht.
Verwende den Sprachumschalter des ausgewählten Adapters. Next Pages nutzt Router-Navigation und ein Sprach-Cookie. TanStack nutzt einfache Links, damit eine neue Anfrage den neuen Katalog laden kann.
Text, Schreibrichtung oder Datumsangaben ändern sich während der Hydration #
Vergleiche die Eingaben auf Server und Client: Katalogversion, Sprache, Werte, Zeitstempel, Zeitzone und Referenzzeitpunkt für relative Zeitangaben. Setze lang und dir des Dokuments im Grundgerüst des Frameworks; der Basis-Provider ändert sie nicht. Teste anschließend das ursprüngliche HTML und die Seite nach der Hydration anhand der Checkliste für serverseitiges Rendering.