コンテンツは1つの言語で用意していても、ユーザーはさまざまな言語でそれを読みます。この API は、そのギャップをプログラムで埋めるためのものです。テキストを送れば、翻訳されて返ってきます。しかも、すべての翻訳は一度設定した ローカライゼーションエンジン を通ります。エンジンは、glossary、ブランドボイス、instructions、ロケールごとのモデル選択 を毎回の呼び出しに適用するため、出力は汎用モデルの推測ではなく、チームが定めた方針どおりの表現になります。
残る判断は1つだけです。一度にどれだけ翻訳するか。単一ロケールなら1回のリクエストで翻訳し、結果をそのままレスポンスから受け取れます。複数ロケールならプラットフォームにまとめて渡し、アプリの応答性を保ったまま、各ロケールを独立したバックグラウンドジョブとして翻訳できます。このページでは、ベース URL、その2つの選択肢、そして次に進む先を紹介します。
この API の前提
これは、プログラムから翻訳するためのリファレンスです。ダッシュボード経由ではなく、自分のコードやパイプラインからローカライズすると決めていて、API キーを持っていることを前提としています。プラットフォームを初めて使うなら、まず理解すべきなのは ローカライゼーションエンジン という考え方です。ここで扱うものはすべて、それを通じて動作します。
このページの内容
ベース URL#
このリファレンスにあるすべての REST エンドポイントは、1つのホスト配下にあります。
https://api.lingo.devすべてのリクエストには、X-API-Key ヘッダーも含めます。このキーは組織単位で発行され、作成時に一度だけ表示されます。送信方法の詳細は Authentication に、リクエストが拒否されたときに何が返るかは Errors and status codes にあります。
翻訳の2つの方法#
どちらのモードでも、裏側で動くのは同じエンジン、同じ用語集、同じブランドボイスです。違うのは、待ち時間をどちらが引き受けるかです。
同期呼び出しでは、1つのロケールペアを翻訳し、その翻訳結果をレスポンスで返します。よりシンプルな方法で、1リクエスト、1レスポンス、利用側で用意する実行用エンドポイントも不要です。単一ロケールが必要で、1回の往復を待てるなら、これが最適です。
ただ、実際にはコンテンツを1つのロケールだけに配信することはほとんどありません。トレーニングモジュールは14言語に展開され、CMS エントリは販売先のすべての市場へ配信されます。ロケールごとに同期呼び出しを1回ずつ実行すれば、14回の往復と、どれか1つが失敗したときのリトライロジックを自分で持つことになります。すべてを1回の同期呼び出しで待てば、最も遅い処理に全体が引っ張られます。そのため、API には非同期モードも用意されています。対象ロケールを指定してコンテンツを一度 POST すれば、すぐに 202 を受け取り、プラットフォームが各ロケールを独立したバックグラウンドジョブとして翻訳します。リトライや失敗の分離はプラットフォーム側が担うため、アプリの応答性を保てます。
ジョブが大きすぎる、遅すぎる、あるいはロケール数が多すぎて待てないなら async を選びましょう。1つのロケールペアを1つのレスポンスで受け取れれば十分なら sync が向いています。以下では async 関連のページを先に紹介しますが、それは扱う内容が多いためです。どちらか一方が「本物の」API というわけではなく、どちらも同じエンジンの異なる使い方です。
非同期: 複数ロケールをジョブとして処理#
1回のリクエストで全ロケールを送信し、結果は完了したものから受け取れます。async API は1回の送信を受けて、対象ロケールごとに1つのジョブを作成し、それぞれの結果を完了した瞬間に webhook または WebSocket で返します。アプリをブロックさせる必要はありません。
同期: 1リクエスト、1レスポンス#
必要なのが1つのロケールペアだけで、往復時間を待てるなら、sync エンドポイントを呼び出してレスポンスから直接結果を取得できます。webhook エンドポイントもポーリングも不要です。
次のステップ#
どちらのモードを選んでも、その背後にあるエンジンは自由に調整できます。まずキーを発行し、次にエンジンが毎回の呼び出しで何をするかを形にしていきます。たとえば、ロケールごとに選ぶモデルや、必ず正確に訳すべき用語などです。
