JSON を翻訳する

コンテキスト、ヒント、保護対象のパスを指定して JSON オブジェクトを送信し、翻訳結果をダウンロードします。

アプリケーションがすでにソースをメモリ内に保持している場合は、ローカライゼーションジョブに JSON オブジェクトを直接渡せます。Lingo.dev はこれを JSON ドキュメントとして保存し、ターゲットロケールごとに出力を生成します。

クイックスタートでは、プログラムの完全なサンプルを紹介しています。このリファレンスでは、JSON 固有のリクエストフィールドについて説明します。

インラインドキュメントを送信する #

X-API-Key に API キーを指定し、今回の送信に対して一貫して使用する Idempotency-Key を設定して、POST /v2/organizations/:orgId/localization/jobs でジョブを作成します。

json
{
  "engineId": "YOUR_ENGINE_ID",
  "sourceLocale": "en",
  "targetLocales": ["de", "fr"],
  "documents": [
    {
      "key": "settings.json",
      "format": {
        "type": "json",
        "options": {
          "context": "Settings dialog in a team collaboration application",
          "hints": { "$.save": ["Button that saves the edited settings"] },
          "lockedKeys": ["$.productName"]
        }
      },
      "source": {
        "content": {
          "save": "Save changes",
          "cancel": "Cancel",
          "productName": "Acme"
        }
      }
    }
  ]
}

ソースは JSON オブジェクトである必要があります。ネストしたオブジェクトや配列も含められます。末端の値が文字列であれば翻訳候補となり、数値、真偽値、ヌル値は元の JSON の型を保持します。文字列として格納された識別子、製品名、URL を変更せずに残す場合は、保護対象に指定してください。

インラインソースでは format.type: "json" を使用します。JSONC やその他のファイル形式の場合は、ファイルのバイト列をアップロードしてください。

コンテキストを追加してコンテンツを選択する #

JSON のオプションは、ドキュメントの format.options 内に指定します。

オプション動作
contextコンテンツの目的や対象読者を説明する、空でないテキスト。
hintsJSONPath クエリを、空でないヒントからなる空でない配列に対応付けます。選択された文字列には、一致するヒントがすべて適用されます。既定値は空のオブジェクトです。
lockedKeys選択したソースの値を翻訳せずにコピーします。既定値は [] です。
preservedKeys選択した値について、以前の翻訳先に値があれば再利用し、なければソースの値をコピーします。既定値は [] です。
ignoredKeys選択した値を出力から除外します。既定値は [] です。
keyScope空でない JSONPath クエリのリストで選択した文字列を再生成します。すべてのターゲットロケールに以前の翻訳が必要です。
termScope空でないソース用語のリストに一致する文字列を再生成します。すべてのターゲットロケールに以前の翻訳が必要です。
injectLocale$.meta.locale など、JSONPath で指定した単一の位置にターゲットロケールを書き込みます。そのサブツリーは翻訳から保護されます。

API リクエストでは JSONPath を使用します。$.title はルートのプロパティを、$.nav.home はネストしたプロパティを、$['nav.home'] はドットを文字として含むキーを、$..productName は任意の深さにあるそのプロパティを選択します。オブジェクトや配列を選択すると、その配下の文字列も含まれます。キー名だけでは、有効な API クエリになりません。

キーに対する制御は、翻訳前に適用されます。無視対象の値は削除され、ロックされたソースの値は、保持対象の翻訳先の値より優先されます。翻訳範囲の選択によって、これらの制御が上書きされることはありません。出力の組み立てと ICU メッセージについては、JSON 形式のリファレンスを参照してください。

termScope は、大文字と小文字を区別し、ソース文字列の一部に一致するかどうかで判定します。リスト内のいずれかの用語に一致すれば、その文字列が選択されます。"cat" は "catalog" にも一致しますが、"login" は "Login" には一致しません。一致した用語だけでなく、選択された文字列全体が再生成されます。keyScope と termScope の両方を指定した場合、文字列は両方の条件を満たす必要があります。部分一致では無関係なメッセージまで含まれる場合は、JSONPath でキーを正確に指定してください。

処理を開始して結果を確認する #

ジョブ作成時のレスポンスに含まれる id を保存します。このジョブが以前のファイルや他のドキュメントも参照している場合は、uploads のすべてのエントリをアップロードしてから、POST /v2/localization/jobs/:id/start を呼び出します。

GET /v2/localization/jobs/:id を取得し、各ドキュメントの targets を確認します。status._tag: "Completed" のターゲットには status.downloadUrl があります。同じ認証情報を使用してその URL からダウンロードすると、JSON オブジェクトを取得できます。ジョブのレスポンス自体に含まれるのは進行状況と成果物のアドレスであり、翻訳済みのオブジェクトではありません。

更新する場合は、既存のドキュメントを更新するの説明に従って、以前のソースと翻訳先の成果物を送信します。遅れて返された結果が新しいコンテンツを上書きしないように、新しいソースのリビジョンをジョブ ID とともに保存してください。