ドキュメントを翻訳する

ソースファイルと以前の翻訳をアップロードし、ローカリゼーションジョブを開始して、翻訳後のファイルをダウンロードします。

ドキュメントジョブでは、ファイルの形式を保ったまま翻訳できます。1つのジョブに複数のファイルと翻訳先言語を指定できます。APIでは、各ファイルの正確なバイト列から算出したSHA-256ハッシュでファイルを識別します。

APIキー、組織ID、エンジンIDが必要です。ファイルのローカリゼーションガイドに、Node.jsの完全なサンプルを掲載しています。

形式を選択する #

各ドキュメントにformat.typeを設定します。

形式種類
JSON / JSONCjson / jsonc
Markdown / MDX / Markdocmd / mdx / markdoc
HTMLhtml
TypeScript / PHPtypescript / php
YAML / ロケールルートYAML / OpenAPI YAMLyaml / yaml-root-key / yaml-openapi
Android / Flutter ARBandroid / flutter
Apple文字列 / 複数形辞書 / 文字列カタログxcode-strings / xcode-stringsdict / xcode-xcstrings
Gettext / XLIFF / SubRippo / xliff / srt
プレーンテキストtxt
ロケールごとに列を設けたCSVテーブルcsv
Javaプロパティproperties
Payloadのコンテンツpayload

形式のリファレンスでは、ファイル構造と制御方法を説明しています。APIのformat.optionsはドキュメント仕様に従います。CLIの設定では、CLI独自のオプション名がこの仕様に合わせて変換されます。たとえば、APIではMarkdownにfrontmatterFieldsを、コンポーネントのプロパティにcomponentPropsを使用します。JSONのキーセレクターにはJSONPathを使用します。

形式のオプションを設定する #

format.optionsを省略すると、既定値が使用されます。選択した種類でサポートされているオプションだけを設定してください。

種類オプション
json, jsoncJSONオプション:キーのルール、スコープ、コンテキスト、ヒント、ロケールの挿入。
typescript, php, yaml, yaml-root-keylockedKeys、preservedKeys、ignoredKeys(既定値:[])。keyScopeとtermScopeは任意で指定できますが、空にはできません。
mdfrontmatterFields(既定値:["$.title", "$.description"])。termScopeは任意で指定できますが、空にはできません。
mdx, markdocMarkdownのオプションに加えて、componentProps(既定値:[])。
htmlハンドラーに組み込まれた翻訳対象の属性に加えて、componentProps(既定値:[])。
xcode-stringsdictlockedKeysとpreservedKeys(既定値:[])。termScopeは任意で指定できますが、空にはできません。
flutter, xcode-strings, xcode-xcstrings, android, yaml-openapitermScopeは任意で指定できますが、空にはできません。
csvkeyColumnでキー列のヘッダーを任意で指定できます(既定値:最初のヘッダーセル)。
propertieslockedKeys、preservedKeys、ignoredKeys(既定値:[])、および任意指定のkeyScope(空の値は不可)。従来形式のパターンとしてキー全体と照合します。ただし、パターンが$で始まる場合は、JSONPathとして照合します。termScopeは任意指定(空の値は不可)。lockedPatterns(既定値:[])は、値の中で翻訳せずに保持する部分を指定するRE2正規表現です。
payload, po, xliff, srt, txt追加のオプションはありません。

キーのルール、キーのスコープ、フロントマターのフィールドにはJSONPathクエリを使用します。termScopeは、大文字と小文字を区別し、指定したいずれかの用語を部分文字列として含むソース単位全体を選択します。"cat"は"catalog"に一致する場合があります。形式がkeyScopeとtermScopeの両方に対応している場合、両方を指定すると、それらの共通部分が選択されます。どちらのスコープにも、マージ先となる既存の翻訳が必要です。選択と再利用の動作は形式によって異なります。詳しくは差分更新を参照してください。これらのAPIオプションは、CLIの--key形式への対応とは異なります。

コンポーネントのプロパティルールには、プロパティ名を指定する空でない配列propsを含めます。必要に応じて、対象を指定した名前のコンポーネントに限定する空でない配列componentsも含められます。componentsを省略すると、すべてのコンポーネントにルールが適用されます。MDXの場合:

json
{
  "type": "mdx",
  "options": {
    "frontmatterFields": ["$.title", "$.description", "$.sidebar.label"],
    "componentProps": [{ "components": ["Callout"], "props": ["title"] }]
  }
}

これにより、選択したフロントマターと、リテラルで指定されたCalloutのタイトルが、ドキュメントの本文とともに翻訳されます。保護されるコードや式、再構築時の動作については、形式のリファレンスを確認してください。

アーティファクトのアドレスを指定してジョブを作成する #

アップロードするバイト列そのものからハッシュを算出します。Node.jsの場合:

js
import { createHash } from "node:crypto";
import { readFile } from "node:fs/promises";

const bytes = await readFile("messages/en.json");
const address = createHash("sha256").update(bytes).digest("hex");

得られたアドレスをドキュメントのsourceに指定して、ジョブを作成します。

json
{
  "engineId": "YOUR_ENGINE_ID",
  "sourceLocale": "en",
  "targetLocales": ["de"],
  "documents": [
    {
      "key": "messages/en.json",
      "format": { "type": "json" },
      "source": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    }
  ]
}

サンプルのアドレスを算出したハッシュに置き換え、返されたジョブIDを保存してください。uploadsには、ストレージに存在しない入力アーティファクトが一覧で返されます。保存済みのコンテンツを再度アップロードする必要はありません。

バイト列をアップロードして開始する #

各uploadsエントリについて、Content-Type: application/octet-streamを指定し、元のバイト列を本文に設定した認証付きのPUTを、そのuploadUrlに送信します。開始する前に、ソースと、参照している以前のファイルをすべてアップロードしてください。

アーティファクトのサイズ上限は、それぞれ25 MiBです。ハッシュが一致しない場合はArtifactChecksumMismatchが、ファイルがサイズ上限を超えた場合はRequestBodyTooLargeが返されます。テキストのハッシュを算出した後、アップロード前に改行コードを変更すると、バイト列が変わり、検証に失敗します。

すべてのアップロードが成功したら、POST /v2/localization/jobs/:id/startを呼び出します。アーティファクトをアップロードできるのは、ジョブの開始前だけです。ジョブの翻訳先ごとの進捗を確認し、返されたURLから翻訳が完了したファイルをダウンロードします。

既存のドキュメントを更新する #

差分更新に備えて、新しいソース、以前のソース、各翻訳先ロケールの現在の翻訳という3つの入力を保持しておきます。次の情報を指定してください。

  • source:新しいソースのアーティファクトアドレス。
  • previousSource:前のリビジョンで使用したソースのアドレス。
  • previousTranslations:利用可能な翻訳ごとに1つの{ "locale": "de", "artifact": "..." }エントリ。

以前の翻訳として渡すバイト列には、ローカルで行った手動の編集も含めてください。形式ハンドラーは、変更のないコンテンツを再利用し、変更されたコンテンツを翻訳できます。通常のJSONでは、以前のソースを省略すると、ソースに変更がないことに基づく再利用ができなくなります。他の形式では、それぞれのマージルールに従って既存の翻訳先コンテンツを取り込めます。ソースが編集されたメッセージと変更されていないメッセージを区別する必要がある場合は、完全なベースラインを保持してください。

keyScopeまたはtermScopeで範囲を限定したリクエストを行うには、すべての翻訳先ロケールに以前の翻訳が必要です。JSON、JSONC、TypeScript、PHPでは、ソースの値に変更がない場合も含めて、選択された文字列を再生成し、既存の翻訳先にマージします。YAML、ロケールルートYAML、OpenAPI YAMLでは、以前のソースを指定すると、選択されたコンテンツのうち変更のないものを再利用できます。XCStringsでは、以前のソースがなくても、埋め込まれた翻訳先の値や、別途指定した翻訳先の値を再利用できます。そのため、選択された単位が必ず新たな翻訳作業の対象になるとは限りません。

再生成をリクエストする前に、使用したい用語やルールをエンジンに指定し、生成された翻訳を確認してください。特定の文言に修正したい場合は、翻訳を直接編集すれば、再生成で意図した表現が得られるかどうかに左右されません。

後続のジョブを作成する前に、PUT /v2/organizations/:orgId/localization/artifacts/:addressを使用し、ファイルのバイト列を本文として認証付きで送信して、ベースラインを保存します。このルートの利用には、組織内のエンジンに対する翻訳アクセス権が必要です。レスポンスにはアーティファクトのメタデータが返されます。同じ25 MiBの上限とハッシュ検証が適用されます。

結果は、まず一時ファイルにダウンロードします。アプリケーションのファイルを置き換える前に、送信したソースのリビジョンと、送信後に翻訳先に加えられた編集内容の両方と比較してください。対応するCLIのワークフローについては、レビュー済みの翻訳を保持するで説明しています。