Recognize

Sie haben einen Text und keinen verlässlichen Hinweis darauf, in welcher Sprache er verfasst ist – einen Kommentar, den ein Nutzer eingegeben hat, einen String aus einer hochgeladenen Datei oder den Inhalt eines eingehenden Support-Tickets. Bevor Sie ihn weiterleiten, übersetzen oder überhaupt korrekt darstellen können, brauchen Sie seine Sprache: welche Sprache, welche Region, welche Schrift und in welche Richtung sie gelesen wird. Recognize schließt diese Lücke mit einem einzigen Aufruf. Sie senden den Text und erhalten eine strukturierte Sprachidentität zurück – so spezifisch, wie der Text es zulässt.

Diese Seite behandelt den gesamten Endpunkt – die Anfrage, die Antwort mit allen zurückgegebenen Feldern, die Language Bindings und das Verhalten der Antwort, wenn der Text keine Region oder Schrift eindeutig erkennen lässt. Es ist ein synchroner Aufruf: Sie senden Text per POST, die Anfrage blockiert während der Analyse, und die Antwort kommt im selben Roundtrip zurück. Die Authentifizierung erfolgt über den gemeinsamen X-API-Key-Header – in Authentication erfahren Sie, wie die Schlüssel funktionieren – und Fehler folgen dem Standard-Fehlermodell.

Anfrage#

POST /process/recognize

Nur text ist erforderlich. labelLocale steuert die Sprache der menschenlesbaren label in der Antwort – setzen Sie sie auf de, und die Bezeichnung für eine französische Eingabe wird auf Deutsch statt auf Englisch zurückgegeben. Das ändert nicht, was erkannt wird, sondern nur, wie das Ergebnis für Sie benannt wird.

{
  "text": "Bonjour le monde",
  "labelLocale": "en"
}

Antwort#

{
  "locale": "fr",
  "language": "fr",
  "region": null,
  "script": null,
  "label": "French",
  "direction": "ltr"
}

Zwei Dinge an dieser Struktur sollte man besonders genau lesen, denn sie machen das Ergebnis nicht nur informativ, sondern wirklich nutzbar.

Erstens ist jeder Code ein veröffentlichter Standard und keine Erfindung von Lingo.dev. locale ist BCP-47; language ist ein ISO 639-Subtag; region ist ISO 3166; script ist ISO 15924. Was auch immer Sie bereits zum Parsen von Sprachen verwenden – Ihre i18n-Bibliothek, ein Intl-Aufruf oder ein CLDR-Lookup – verarbeitet diese Ausgabe direkt. Sie müssen sich nicht an ein proprietäres Codesystem anpassen, sondern erhalten dieselben Bezeichner, die Ihr Stack ohnehin schon versteht.

Zweitens sind region und script bewusst nullable. Sie werden nur dann ausgefüllt zurückgegeben, wenn der Text sie tatsächlich erkennen lässt – genau darum geht es in den nächsten beiden Abschnitten, und genau das verhindert, dass der Endpunkt rät.

Region und Schrift werden nur zurückgegeben, wenn der Text sie erkennen lässt#

Die naheliegende Sorge bei jeder Spracherkennung ist, dass sie zu weit geht: dass sie einem Text eine Region oder ein Schriftsystem zuweist, die der Text nie belegt hat, und Sie Ihre Logik dann auf einer Vermutung aufbauen. Recognize macht das Gegenteil. Es meldet ein Subtag nur dann, wenn die Evidenz dafür ausreicht, und gibt andernfalls null zurück.

Wenn regionale Merkmale im Text vorhanden sind – zum Beispiel brasilianisch-portugiescher Wortschatz –, enthält die Antwort das vollständige Tag (pt-BR). Wenn die regionale Variante nicht unterscheidbar ist, wird nur das Sprach-Subtag zurückgegeben (pt):

{
  "locale": "pt-BR",
  "language": "pt",
  "region": "BR",
  "script": null,
  "label": "Portuguese (Brazil)",
  "direction": "ltr"
}

{
  "locale": "pt",
  "language": "pt",
  "region": null,
  "script": null,
  "label": "Portuguese",
  "direction": "ltr"
}

Dieselbe Sprache, zwei ehrliche Antworten. Der erste Text enthielt genug Hinweise, um die Region zu benennen; der zweite nicht, daher ist region gleich null und locale reduziert sich auf pt. Für script gilt dieselbe Regel in die andere Richtung: Es ist null, wenn das Schriftsystem die Standardschrift der Sprache ist – etwa Lateinisch für Französisch – und wird nur genannt, wenn die Schrift das unterscheidende Merkmal ist.

Deshalb ist locale das Feld, auf dem Sie aufbauen sollten. Es ist immer das spezifischste Tag, das der Text stützt – pt-BR, wenn die Evidenz dafür vorliegt, pt, wenn nicht – sodass Ihnen das Lesen von locale automatisch die richtige Granularität liefert, ohne dass Sie es aus den Einzelteilen neu zusammensetzen oder eine überzeugend wirkende Region hinterfragen müssen, die in Wirklichkeit nur geraten war.

direction ist da, damit Sie vor dem Übersetzen rendern können#

Spracherkennung ist selten das eigentliche Ziel – normalerweise erkennen Sie eine Sprache, um mit dem Text etwas zu tun, und oft ist das Erste, was Sie tun, ihn anzuzeigen. direction ist genau deshalb in der Antwort enthalten: Es sagt Ihnen, ob der Text von links nach rechts oder von rechts nach links gelesen wird, sodass Sie dir="rtl" setzen, ein Layout wählen oder eine Schriftart auswählen können, noch bevor überhaupt ein Übersetzungsschritt stattfindet. Arabischer Text kommt als "rtl" zurück; das französische Beispiel oben kommt als "ltr" zurück. Sie müssen keine eigene Tabelle für Sprache und Schreibrichtung pflegen – der Endpunkt, der die Sprache identifiziert, liefert Ihnen zugleich die Darstellungsinformation, die Sie zuerst brauchen.

Beispiele#

Ein einzelner POST mit dem Text und einer optionalen labelLocale. Die Antwort ist das oben gezeigte strukturierte Sprachobjekt.

const response = await fetch(
  "https://api.lingo.dev/process/recognize",
  {
    method: "POST",
    headers: {
      "X-API-Key": "your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      text: "Bonjour le monde",
      labelLocale: "en",
    }),
  }
);

const result = await response.json();
// { locale: "fr", language: "fr", label: "French", direction: "ltr", ... }

Nächste Schritte#

Der häufigste Grund, eine Sprache zu erkennen, ist, darauf zu reagieren – meist, indem man sie übersetzt. Recognize teilt Ihnen die Quell-Sprache mit; die Lokalisierungsendpunkte übernehmen den Rest.