M6の翻訳API　動き

APIパラメータと挙動をもう一度クリアにまとめます👇

このAPIがやっていること（いまの実装）

• 取得した行の i18n対象カラム（label_i18n / help_i18n / placeholder_i18n / unit_i18n / selection_items[].label_i18n / notes）を再帰的に走査。
• 指定した言語キー（target）が未設定の場所だけを補完します。既存値は上書きしません（idempotent）。
• selection_items のような 配列・ネストも再帰で補完します。
• DBに updated_at があれば NOW() を入れます。
• いまの実装は portal_fields テーブルに書き戻す方式です（別テーブル集約に切り替えるときは新APIにします）。

---

パラメータの意味

target（例: en_US）

• 補完したい言語キー。
• 既に target が入っている箇所は触りません（上書きしない）。

only_missing（既定: true）

• true: SQL段階で「トップレベルの i18n 列（label/help/placeholder/unit）に target キーが無い」行だけを先に絞り込みます。
  ※ selection_items の内側などネストは SQL では絞り込まず、後段の Python再帰で判定します。
• false: SQLでの欠落フィルタを使わず、**全件（limit件）**を対象にします（とはいえ補完は「未設定の箇所だけ」です）。

limit（既定: 100, 1〜1000）

• 1回の処理で取得・チェックする最大行数（安全運用や段階反映のためのブレーキ）。

dry_run（既定: false）

• true: 書き込みしません。再帰補完の結果を preview_samples（最大20件）として before/after で返します。
  → 変更予定の差分を確認するための安全プレビュー
• false: 実際にDBへ書き込みます。

ids（例: ids=12&ids=34 または 12,34）

• 指定IDの行に限定して実行（ピンポイント検証に便利）。

---

レスポンスの読み方

• processed: 取得してチェックした行数（limitやidsの影響を受けます）
• updated: 実際に変更があった行数（dry_run=true のときはプレビュー件数）
• preview_samples: dry_run=true 時のみ。変更の before/after を最大20件収録
• note: 上書きしない・再帰補完する、等の注意

---

よく使う呼び方（例）

1) まずはプレビュー（安全確認）

# 未設定のen_USだけ補完 → 書き込まず差分だけ見る
curl -s -X POST "http://api.local:8080/fields/translate?target=en_US&only_missing=true&limit=50&dry_run=true" | jq .

2) 問題なければ本番反映

curl -s -X POST "http://api.local:8080/fields/translate?target=en_US&only_missing=true&limit=50&dry_run=false" | jq .

3) 特定行だけ試す（単体検証）

curl -s -X POST "http://api.local:8080/fields/translate?target=en_US&only_missing=false&limit=10&dry_run=true&ids=123" | jq .

---

補足（内部仕様のポイント）

• SQLの「欠落チェック」は ?（has-key）演算子でトップレベルi18n列のみ実施 → ネストはPythonで判定。
• 何かのi18n列が NULL の場合でも安全にスキップする実装。
• スキーマに存在しない列は自動スキップ（例えばまだ placeholder_i18n が無ければ対象外）。