Lingo.devのローカライゼーションAPIは、設定済みのローカライゼーションエンジンを通してキー・バリューデータを翻訳します。HTTPリクエストを1回送るだけで、文字列を渡せば翻訳済みの文字列が返ってきます。用語集のルール、ブランドボイス、モデル選択も自動で適用されます。
APIを使うタイミング#
ローカライゼーションAPIは、翻訳をビルド時ではなく、実行時やバックエンドサービス内で行う場合に適しています。
| ユースケース | 例 |
|---|---|
| 動的コンテンツ | データベースに保存されたコース説明、レッスンタイトル、クイズ問題を翻訳する |
| ユーザー生成コンテンツ | レビュー、コメント、フォーラム投稿を必要に応じて翻訳する |
| APIレスポンス | ユーザーのロケールに応じて、ローカライズ済みのコンテンツをバックエンドから返す |
| 通知 | メール件名、プッシュ通知、アプリ内メッセージを送信前に翻訳する |
ビルド時と実行時
コンテンツが静的ファイル（JSON、Markdown、.strings）にあるなら、CLIやCI/CD integrationのほうが適しています。APIは、バックエンドでコンテンツをローカライズする用途向けに設計されています。
前提条件#
ローカライゼーションエンジンを作成する
すべてのAPIコールはローカライゼーションエンジンを通って実行されます。これは、どのLLMモデル、用語集、ブランドボイス、指示を適用するかを決める設定です。Lingo.devのダッシュボードで作成してください。
コンテンツをローカライズする#
ソースロケール、ターゲットロケール、キー・バリューデータを指定して、localizeエンドポイントにPOSTリクエストを送信します。リクエスト/レスポンスの完全なスキーマは、API referenceにまとまっています。
この例では、JavaScriptコース内の段落をスペイン語に翻訳します。
const content = {
intro: "JavaScript is a programming language that powers the interactive elements of most websites. When you click a button, submit a form, or see content update without the page reloading, JavaScript is making that happen.",
};
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: "es",
data: content,
}),
});
const { data } = await response.json();
// {
// intro: "JavaScript es un lenguaje de programacion que impulsa los elementos interactivos de la mayoria de los sitios web. Cuando haces clic en un boton, envias un formulario o ves contenido actualizarse sin que la pagina se recargue, JavaScript lo esta haciendo posible."
// }キーはそのまま保持されます。introを送ると、introが返ってきます。エンジンが翻訳するのは値だけです。
キーの構造化#
dataオブジェクトはフラットで、各キーは1つの文字列に対応します。意味の文脈が伝わるようにキーを設計してください。
const content = {
"variables.intro": "Variables are containers for storing data values. In JavaScript, you declare them with let, const, or var.",
"variables.example": "Use const for values that never change, and let for values that do.",
"variables.exercise": "Declare a variable called age and assign it your age as a number.",
};意味ごとに整理されたキーは、ローカライゼーションエンジンがより自然で一貫性のある翻訳を生成するのに役立ちます。エンジンは、1回のリクエストに含まれるすべてのキーを関連する文脈として捉えるため、variables.introとvariables.exampleは別々に送るより一緒に送るほうが、より一貫して翻訳されます。
技術用語
「const」や「let」のような語は、翻訳すべきでないプログラミング用語です。用語集を使って翻訳対象外として指定するか、ロケールごとの適切な表現にマッピングしてください。Claude CodeやCursorのようなAIコーディングアシスタントを使っている場合は、Localization MCPを使うことで、開発ワークフローの中で用語集ルールの設定を進めやすくなります。
保存時にローカライズする#
一般的なのは、コンテンツを読むタイミングではなく、作成時や更新時に翻訳するパターンです。こうしておけば、ユーザーがリクエストした時点で翻訳済みコンテンツはすでにデータベースに保存されています。
app.post("/api/lessons", async (req, res) => {
const lesson = await db.lessons.create(req.body);
const content = {
intro: lesson.intro,
example: lesson.example,
exercise: lesson.exercise,
};
const targetLocales = ["es", "fr", "de", "ja"];
const translations = await Promise.all(
targetLocales.map(async (targetLocale) => {
const response = await fetch("https://api.lingo.dev/process/localize", {
method: "POST",
headers: {
"X-API-Key": process.env.LINGODOTDEV_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
sourceLocale: "en",
targetLocale,
data: content,
}),
});
const { data } = await response.json();
return { locale: targetLocale, data };
})
);
await db.lessonTranslations.insertMany(
translations.map((t) => ({
lessonId: lesson.id,
locale: t.locale,
...t.data,
}))
);
res.json(lesson);
});その後のローカライズ済みコンテンツの読み出しは、シンプルなデータベース参照だけで済みます。読み取り時にAPIコールは不要です。
app.get("/api/lessons/:id", async (req, res) => {
const locale = req.query.locale || "en";
if (locale === "en") {
const lesson = await db.lessons.findById(req.params.id);
return res.json(lesson);
}
const translation = await db.lessonTranslations.findOne({
lessonId: req.params.id,
locale,
});
res.json(translation);
});