Localize

文字列1つ、あるいは小さな文字列オブジェクトを、今すぐ別の言語にしたい。フォームのラベル、通知、ユーザーが待っている短いUIコピーなどです。たった1回のやり取りのために webhook エンドポイントを立てたり、ジョブをポーリングしたりはしたくない。テキストを送って、その場で翻訳結果を受け取りたい。

そのためにあるのが、同期の Localize エンドポイントです。1回のリクエストで、同じ構造のまま翻訳済みデータが返ります。 ソースロケールとターゲットロケールを指定してキーと値のコンテンツをPOSTすると、エンジンの翻訳が完了するまで呼び出しはブロックされ、レスポンスでは値だけが翻訳され、構造はそのままの同じオブジェクトが返されます。追跡するジョブも、2回目の呼び出しも必要ありません。

これは単なる汎用モデルへの呼び出しではありません。設定済みのローカライゼーションエンジン、つまりその glossary、ブランドボイス、instructions、そしてロケールごとの モデル選択 を通して翻訳が実行されます。使われるのは async API と同じエンジンです。違うのは返し方だけです。async は1つのリクエストを複数のロケールに展開し、結果が揃い次第返します。一方この呼び出しは、1組のロケールだけを処理して、その場で結果を返します。

このページの内容

• リクエスト
• レスポンス
• 例
• ローカライズ時の処理
• 次のステップ

リクエスト#

POST /process/localize

X-API-Key ヘッダーで認証します。キーは組織スコープで、組織内のすべてのエンジンにアクセスできます。生成方法については Authentication を、完全なエラーモデルについては Errors and status codes を参照してください。

{
  "engineId": "eng_abc123",
  "sourceLocale": "en",
  "targetLocale": "de",
  "data": {
    "greeting": "Hello, world!",
    "cta": "Get started"
  },
  "hints": {
    "cta": ["Landing page", "Primary button"]
  }
}

レスポンス#

レスポンスには、送信したものと同じ構造の翻訳済みコンテンツに加えて、それを生成したモデルとリクエスト単位のコストが含まれます。同じキーが、同じネスト構造のまま返ってくるため、コード側ではすでに知っている構造からそのまま翻訳結果を取り出せます。

usage オブジェクトには、この呼び出しのコスト内訳が含まれているため、別途請求情報を参照しなくても利用額を把握できます。

{
  "sourceLocale": "en",
  "targetLocale": "de",
  "data": {
    "greeting": "Hallo, Welt!",
    "cta": "Jetzt starten"
  },
  "model": "anthropic/claude-sonnet-4.5",
  "usage": {
    "inputTokens": 2789,
    "outputTokens": 861,
    "cacheReadTokens": 0,
    "cacheWriteTokens": 0,
    "llmCost": 0.02129,
    "localizationCost": 0.001722,
    "cost": 0.023012
  }
}

例#

同じ呼び出しを5つの言語で示します。分かりやすさのため、各例ではフラットなオブジェクトを送っていますが、data はネストされたオブジェクトや配列にも対応しており、レスポンスは送信した構造のまま返されます。

const response = await fetch(
  "https://api.lingo.dev/process/localize",
  {
    method: "POST",
    headers: {
      "X-API-Key": "your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      engineId: "eng_abc123",
      sourceLocale: "en",
      targetLocale: "de",
      data: {
        greeting: "Hello, world!",
        cta: "Get started",
      },
    }),
  }
);

const { data } = await response.json();
// { greeting: "Hallo, Welt!", cta: "Jetzt starten" }

ローカライズ時の処理#

1回の POST の裏側では、一連の処理が走っています。そして、それを知っておく価値があります。というのも、その処理こそが、出力を単発のモデル推測ではなく、既存のローカライズ済みコンテンツ全体と整合したものにしているからです。リクエストがこのエンドポイントに到達すると、エンジンは完全な設定を次の順序で適用します。

1. モデル選択 – ロケールペアに一致する中で、最優先の LLM model を選択します。ロケール固有のモデルは、ワイルドカード（*）モデルより優先されます。プライマリモデルが失敗した場合、エンジンは次順位のモデルへ自動的にフォールバックします。

2. ブランドボイス – ターゲットロケール用の ブランドボイス を読み込み、ロケール固有のものがなければワイルドカードのブランドボイスにフォールバックします。

3. Instructions – ワイルドカード instructions を含め、ターゲットロケールに一致するすべての instruction を読み込みます。

4. 用語集検索 – 入力値を検索可能なチャンクに分割し、埋め込みを生成したうえで、エンジンの glossary に対してベクトル類似検索を実行します。一致した用語は厳密な訳語を強制するか、非翻訳語としてマークされ、そのまま通過します。

5. 生成 – 構成済みのプロンプトを選択されたモデルに送り、その後 JSON レスポンスを解析・検証します。

これは async API がジョブごとに実行するのと同じエンジン処理パイプラインです。sync を async の代わりに呼び出しても変わるのは結果の返し方だけで、翻訳の生成方法は変わりません。つまり、ここで翻訳された文字列と async ジョブで翻訳された同じ文字列は、同じ用語集の用語と同じトーンに基づいた結果になります。

次のステップ#