Recognize

手元にテキストはあるのに、それが何語なのかを信頼して判断できる記録がない。そんな場面はよくあります。たとえば、ユーザーが入力したコメント、アップロードされたファイル内の文字列、受信したサポートチケットの本文などです。振り分けるにも、翻訳するにも、正しく表示するにも、その前に必要なのはロケールです。どの言語か、どの地域か、どの文字体系か、そしてどちら向きに読むのか。Recognize なら、その不足を1回の呼び出しで埋められます。テキストを送るだけで、テキストが示せる範囲で最も具体的な、構造化されたロケール情報が返ってきます。

このページでは、リクエスト、レスポンスとその全フィールド、各言語バインディング、さらにテキストから地域や文字体系を特定できない場合にどう返るかまで、エンドポイント全体を説明します。これは同期呼び出しです。テキストをPOSTすると、その解析が終わるまでリクエストは待機し、レスポンスは同じ往復の中で返されます。認証には共通の X-API-Key ヘッダーを使用します。キーの仕組みについては Authentication を参照してください。エラーはすべて standard error model に従います。

リクエスト#

POST /process/recognize

必須なのは text だけです。labelLocale は、レスポンス内の人が読める label をどの言語で返すかを指定します。これを de に設定すると、フランス語の入力に対するラベルは英語ではなくドイツ語で返されます。変わるのは結果の呼び方だけで、何が検出されるかは変わりません。

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

レスポンス#

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

このレスポンス形式で特に注意して見てほしい点が2つあります。単に情報を返すだけでなく、実際に使える結果になっている理由はここにあります。

まず、ここで返されるコードはどれも公開標準であり、Lingo.dev 独自のものではありません。locale は BCP-47、language は ISO 639 のサブタグ、region は ISO 3166、script は ISO 15924 です。つまり、すでにロケールの処理に使っているもの—i18nライブラリ、Intl 呼び出し、CLDR参照など—で、この出力をそのまま扱えます。独自のコード体系に合わせて調整する必要はありません。返ってくるのは、あなたのスタックがすでに理解している識別子そのものです。

次に、region と script が null になりうるのは意図的です。値が入るのは、テキストが実際にそれを示しているときだけ。これが次の2つのセクションで扱うポイントであり、このエンドポイントが推測をしない理由でもあります。

地域と文字体系が返るのは、テキストにそれが現れているときだけ#

言語検出でよくある不安は、必要以上に踏み込んでしまうことです。つまり、証拠のないテキストに地域や表記体系を勝手に付け、その推測を前提にロジックを組んでしまうこと。Recognize はその逆です。根拠があるときにだけサブタグを返し、根拠がなければ null を返します。

地域を示す手がかりがテキスト内にある場合—たとえばブラジル系ポルトガル語の語彙がある場合—レスポンスには完全なタグ（pt-BR）が含まれます。地域差を見分けられない場合は、言語サブタグだけが返ります（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"
}

同じ言語でも、誠実な答えは2通りありえます。最初のテキストには地域を特定するだけの情報がありました。2つ目にはそれがなかったため、region は null になり、locale は pt に縮約されます。script も逆方向から同じルールに従います。文字体系がその言語のデフォルト—たとえばフランス語のラテン文字—であれば null になり、文字体系そのものが見分ける決め手になる場合にだけ明示されます。

だからこそ、実装の軸にすべきなのは locale です。ここには常に、テキストが裏づけられる範囲で最も具体的なタグが入ります。根拠があれば pt-BR、なければ pt。つまり locale を読むだけで、適切な粒度を自動的に得られます。各パーツを自分で組み立て直したり、もっともらしく見える地域情報が実は推測だったのではと疑ったりする必要はありません。

direction があるから、翻訳の前に表示できる#

言語検出は、それ自体が目的であることはほとんどありません。たいていは、そのテキストに対して何かをするための前段です。そして最初にやることの1つが、表示であることは少なくありません。レスポンスに direction が含まれているのは、まさにそのためです。テキストが左から右に読むのか、右から左に読むのかが分かるので、翻訳の前に dir="rtl" を設定し、レイアウトを選び、フォントを決められます。アラビア語のテキストなら "rtl"、上のフランス語の例なら "ltr" が返ります。言語ごとの方向対応表を自前で管理する必要はありません。言語を特定するエンドポイントが、最初に必要な表示上の情報まで一緒に返してくれます。

例#

テキストと任意の labelLocale を含めて1回POSTするだけ。レスポンスとして、上記の構造化されたロケールオブジェクトが返ります。

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", ... }

次のステップ#

言語を検出する一般的な理由は、その結果を使って何かを行うことです。最も多いのは翻訳です。Recognize でソースロケールを特定したら、その先はローカライゼーション用エンドポイントに任せられます。