copy_tuner_client 1.1.5 → 1.2.1

data/skills/copy-tuner-to-locales-migrate-prefix/references/local-first-regexp.md

@@ -0,0 +1,72 @@
+# local_first_key_regexp の使い方
+
+SKILL.md 手順 7 の詳細。prefix 単位移行の核心となる gem オプション。
+
+## 何をするオプションか
+
+[copy-tuner-ruby-client #110](https://github.com/SonicGarden/copy-tuner-ruby-client/pull/110) で
+`Configuration#local_first_key_regexp` が追加された。`I18nBackend#lookup` は次のように動く:
+
+```ruby
+# locale を除いたキー（例: "views.foo.bar"）が regexp にマッチしたら…
+if local_first_key?(key_without_locale)
+  return super   # ← I18n::Backend::Simple に委譲。CopyTuner キャッシュもアップロードキューも触らない
+end
+# マッチしなければ従来どおり CopyTuner キャッシュ優先 → 無ければ super
+```
+
+判定は `key_without_locale.to_s.match?(local_first_key_regexp)` の単純マッチ。
+
+## 完全分離の意味
+
+マッチキーは **CopyTuner を一切参照しない**。つまり:
+
+- ローカル YAML に値があればそれを返す。
+- ローカル YAML に**無ければ即 `nil`（未訳）**。CopyTuner へフォールバックしない。
+- 空キーのアップロードキュー投入もしない（`Cache#[]=` の単一関門で抑止）。
+- CopyRay のオーバーレイマーカー（`<!--COPYRAY key-->`）も注入されない（編集できないキーを編集可能と誤認
+  させないため）。
+
+この「無ければ未訳」の挙動こそが、**移行漏れ（ローカルへ書き忘れたキー）を未訳として顕在化させる**仕組み。
+だから移行のたびに `translation missing` チェック（SKILL.md 手順 8）が効く。
+
+## regexp は単一・配列非対応
+
+`local_first_key_regexp` は単一の `Regexp` を取る（`attr_accessor`、デフォルト `nil`）。**配列は渡せない**。
+複数 prefix を移行済みにするには **1 本の正規表現に積み上げる**。`Regexp.union` を使うのが安全:
+
+```ruby
+config.local_first_key_regexp = Regexp.union(
+  /\Adevise\./,
+  /\Aice_cube\./,
+  /\Arestrict_dependent_destroy\./,
+  /\Aviews\./,
+)
+# => /(?-mix:\Adevise\.)|(?-mix:\Aice_cube\.)|.../ 相当
+```
+
+`Regexp.union` はメタ文字のエスケープを自動でやり、要素を OR でつなぐので、prefix を 1 行ずつ足すだけで済む。
+手書きの `/\A(devise|ice_cube|...)\./` でも等価だが、union のほうが追記時のミスが少ない。
+
+## `\A` アンカー必須
+
+各 prefix は **`\A` で先頭アンカー**する。キーは locale 除去後なので `\A` 起点でよい。
+
+- `\A` 無しの `/views\./` は `reviews.foo` の `views.` 部分にもマッチしてしまう（部分マッチ事故）。
+- `\Aviews\.` なら `views.` で始まるキーだけにマッチする。
+- `views` 配下を更に刻むなら `\Aviews\.users\.` のように 2 階層目までアンカーできる。
+
+ドット `.` は正規表現のメタ文字なので、prefix 区切りのドットは `\.` とエスケープする
+（`/\Aviews\./`。`Regexp.union` に文字列を渡す場合は自動エスケープされるが、Regexp リテラルを渡すときは自分で
+書く）。
+
+## deprecated な exclude_key_regexp との違い
+
+| | `local_first_key_regexp` | `exclude_key_regexp`（非推奨） |
+|---|---|---|
+| 対象キー | locale を**除いた**キー（`views.foo`） | locale を**含む**キー（`ja.views.foo`） |
+| 作用タイミング | lookup（読み込み）時 | upload（送信）時 |
+| 効果 | ローカル YAML を優先（完全分離） | サーバへのアップロードを抑止するだけ |
+
+`exclude_key_regexp` は PR #110 で非推奨化された（設定すると `ActiveSupport::Deprecation` 警告が出る）。
+移行では使わない。もし既存設定に `exclude_key_regexp` があれば、cleanup スキルで gem ごと撤去される。

data/skills/copy-tuner-to-locales-migrate-prefix/references/verification-per-prefix.md

@@ -0,0 +1,63 @@
+# prefix 移行後の検証
+
+SKILL.md 手順 8 の詳細。対象 prefix を `local_first_key_regexp` に足した後、その範囲がローカルだけで解決する
+ことを確かめる。完全分離（マッチキーは CopyTuner を見ない）なので、ローカルへの書き忘れは未訳として現れる。
+
+## 1. regexp が意図どおりマッチするか
+
+gem の判定そのものを使って、今回の prefix のキーがマッチし、隣接キーが誤マッチしないことを確認する。
+
+```bash
+bin/rails runner 'p [
+  CopyTunerClient.configuration.local_first_key?("views.foo.bar"),   # => true を期待
+  CopyTunerClient.configuration.local_first_key?("reviews.foo")      # => false を期待（部分マッチ事故の確認）
+]'
+```
+
+## 2. テスト
+
+プロジェクトの品質コマンドに従う。多くの Rails プロジェクトでは:
+
+```bash
+docker compose up -d db   # 未起動なら
+bundle exec rspec
+```
+
+`translation missing` が出ないこと。完全分離した prefix のキーがローカル YAML に揃っていないと、ここで
+未訳が顕在化する（それが狙い）。落ちたら、抜き出したサブツリーに漏れがないか・配置ファイルがロードされて
+いるかを確認する。
+
+## 3. 未翻訳キーの検出
+
+対象 prefix が関わる主要画面・フローを動かし、`translation missing` が出ないか確認する。
+ログから機械的に拾うなら:
+
+```bash
+grep -rni 'translation missing' log/ tmp/ 2>/dev/null || echo 'none'
+```
+
+より厳密にやるなら、開発・テスト環境で `config.i18n.raise_on_missing_translations = true` を一時的に
+有効化してテストを流し、未定義キーで例外が出るかを確認する手もある（任意・恒久設定にするかはプロジェクト判断）。
+
+## 4. i18n の主要参照が解決するか
+
+移行した prefix に応じて、影響しやすい参照パターンを主要画面または rails runner で確認する:
+
+- `views.*` を移したら … ビューの `t('...')` / `t('.lazy_key')`
+- `activerecord.attributes` を移したら … `Model.human_attribute_name(:attr)`（CSV ヘッダ・フォームラベル）
+- `activerecord.models` を移したら … `Model.model_name.human`
+- `activerecord.enums` を移したら … enum の表示名（`human_enum_name` 等のヘルパ経由）
+
+例:
+
+```bash
+bin/rails runner 'puts [User.model_name.human, User.human_attribute_name(:name)].inspect'
+```
+
+`translation missing` を含まず、期待する日本語が返ること。
+
+## 5. 移行していない prefix が壊れていないこと
+
+未移行 prefix は `local_first_key_regexp` にマッチしないので、引き続き CopyTuner から引かれる。今回の移行で
+未移行 prefix の表示が変わっていないことも、主要画面で軽く確認しておく（regexp のアンカー漏れで意図せず
+広くマッチしていないかの確認も兼ねる）。

data/skills/copy-tuner-to-locales-migrate-prefix/scripts/migrate_prefix.rb

@@ -0,0 +1,279 @@
+# frozen_string_literal: true
+
+# copy_tuner → config/locales prefix-unit migration script (SKILL.md step 6).
+#
+# Run via `bin/rails runner` so that the Rails i18n load path and CopyTuner
+# configuration are available:
+#
+#   bin/rails runner .claude/skills/copy-tuner-to-locales-migrate-prefix/scripts/migrate_prefix.rb \
+#     -- --prefix date --export tmp/copy_tuner_all.yml --out config/locales/0010_date.yml
+#
+# What it does, in one pass:
+#   (1) Place : extract the target prefix subtree from the 0000_original_*.yml
+#       originals (load-order deep_merge), deep_merge the export subtree on top
+#       (export wins for string blurbs), then re-apply the originals'
+#       non-representable values (arrays/symbols/numbers/booleans such as the
+#       `date.order` symbol array) last so a corrupted export value cannot
+#       overwrite them, and write it to --out.
+#   (2) Static guards : YAML round-trip, --out is on the i18n load path, every
+#       leaf key matches the prefix regexp.
+#   (3) Leak check : simulate the original-deletion in memory and resolve every
+#       target-prefix key through a fresh I18n::Backend::Simple. A key that goes
+#       missing after deletion is a migration leak.
+#   (4) Gate : only when there are zero leaks, prune the prefix subtree from the
+#       originals on disk. Any leak aborts with the originals untouched.
+#
+# 対象 locale はプロジェクトの I18n.available_locales を実行時に参照して決める（default_locale を先頭に並べる）。
+# `--locales ja,en` で明示上書きできる（fixture を使った検証用。指定時は指定順を尊重する）。
+
+require 'optparse'
+require 'yaml'
+
+# NOTE: `bin/rails runner` は Kernel#abort が投げる SystemExit を握りつぶし終了コードが 0 になる
+# （実機確認済み）。中断を呼び出し側へ確実に伝えるため、abort ではなく warn + exit(1) を使う。
+def die(message)
+  warn message
+  exit(1)
+end
+
+# ---- 引数 ----
+options = {}
+parser =
+  OptionParser.new do |opts|
+    opts.banner = 'Usage: bin/rails runner migrate_prefix.rb -- --prefix PREFIX --export PATH --out PATH [--regexp PATTERN] [--originals-glob GLOB]'
+    opts.on('--prefix PREFIX', 'ドット区切りの対象 prefix（例: date / activerecord.attributes）') { |v| options[:prefix] = v }
+    opts.on('--export PATH', '全件 export YAML（手順3で出力）') { |v| options[:export] = v }
+    opts.on('--out PATH', '移行分の出力先（例: config/locales/0010_date.yml）') { |v| options[:out] = v }
+    opts.on('--regexp PATTERN', 'leaf キー検証用の正規表現（省略時は prefix から \A<prefix>\. を生成）') { |v| options[:regexp] = v }
+    opts.on('--originals-glob GLOB', 'オリジナルファイルの glob（既定: config/locales/0000_original_*.yml）') { |v| options[:originals_glob] = v }
+    opts.on('--locales LIST', 'カンマ区切りの対象 locale（既定: I18n.available_locales。検証用の上書き）') { |v| options[:locales] = v }
+  end
+# `bin/rails runner script -- ...` の `--` 以降だけを渡したいが、runner が剥がさない環境もあるため両対応。
+argv = ARGV.include?('--') ? ARGV[(ARGV.index('--') + 1)..] : ARGV
+parser.parse!(argv)
+
+die(parser.banner) unless options[:prefix] && options[:export] && options[:out]
+
+PREFIX = options[:prefix]
+prefix_keys = PREFIX.split('.')
+
+# 対象 locale 群。--locales 指定時はその順を尊重、未指定なら default_locale を先頭にした available_locales。
+LOCALES =
+  if options[:locales]
+    options[:locales].split(',').map(&:strip).reject(&:empty?)
+  else
+    ([I18n.default_locale.to_s] + I18n.available_locales.map(&:to_s)).uniq
+  end
+# 黙って 'ja' に倒すと将来 locale 追加時にサイレント脱落を招くため、空なら明示的に中断する。
+die('対象 locale が空。I18n.available_locales が取れているか（Rails 環境のロード）、--locales の指定を確認すること。') if LOCALES.empty?
+# 既定の regexp は prefix に \A アンカーを付けたもの（手順7の local_first_key_regexp と整合させる）。
+regexp = options[:regexp] ? Regexp.new(options[:regexp]) : /\A#{Regexp.escape(PREFIX)}\./o
+originals_glob = options.fetch(:originals_glob, 'config/locales/0000_original_*.yml')
+
+# ---- ヘルパ ----
+
+# ネスト Hash を非破壊 deep merge（右辺優先）。配列・スカラはそのまま右辺で置換。
+def deep_merge(base, override)
+  base.merge(override) do |_key, b, o|
+    b.is_a?(Hash) && o.is_a?(Hash) ? deep_merge(b, o) : o
+  end
+end
+
+def deep_merge!(base, override)
+  base.replace(deep_merge(base, override))
+end
+
+# YAML をロードして指定 locale ルート（例 `ja:`）配下の Hash を返す。シンボル（date.order の :year 等）を許可。
+def load_locale_tree(path, locale)
+  raw = YAML.safe_load_file(path, permitted_classes: [Symbol], aliases: true) || {}
+  raw[locale] || {}
+end
+
+# prefix（["date"] や ["activerecord","attributes"]）のサブツリーを掘り出す。無ければ nil。
+def dig_prefix(tree, keys)
+  keys.reduce(tree) do |node, key|
+    return nil unless node.is_a?(Hash) && node.key?(key)
+
+    node[key]
+  end
+end
+
+# prefix サブツリーを {"date" => {...}} のように prefix で包んだ Hash にして返す（無ければ {}）。
+def extract_prefix(tree, keys)
+  sub = dig_prefix(tree, keys)
+  return {} if sub.nil?
+
+  keys.reverse.reduce(sub) { |acc, key| { key => acc } }
+end
+
+# prefix サブツリーを取り除いた新しい Hash を返す。空になった親も刈る（非破壊）。
+def prune_prefix(tree, keys)
+  head, *rest = keys
+  return tree unless tree.is_a?(Hash) && tree.key?(head)
+
+  dup = tree.dup
+  if rest.empty?
+    dup.delete(head)
+  else
+    pruned_child = prune_prefix(dup[head], rest)
+    if pruned_child.is_a?(Hash) && pruned_child.empty?
+      dup.delete(head) # 空親を刈る
+    else
+      dup[head] = pruned_child
+    end
+  end
+  dup
+end
+
+# ネスト Hash の全 leaf を「ドット区切りキー => 値」で返す。配列・シンボル・nil 値は leaf として扱い、
+# その中までは展開しない（date.order の [:year,...] は date.order 1 個）。
+def leaf_entries(tree, prefix = [])
+  tree.each_with_object({}) do |(key, value), acc|
+    path = prefix + [key]
+    if value.is_a?(Hash) && !value.empty?
+      acc.merge!(leaf_entries(value, path))
+    else
+      acc[path.join('.')] = value
+    end
+  end
+end
+
+# ネスト Hash から「非表現値（非 String・非 Hash の leaf）だけ」を残したネスト Hash を返す。
+# 配列・シンボル・数値・真偽値・nil が対象。String leaf は捨てる（export 勝ちに委ねる）。
+# copy_tuner は flat な文字列 blurb しか持てず、これらは export に出てこない／壊れて出る可能性がある。
+# orig 由来のこの結果を最後に deep_merge することで、壊れた export 値が非表現値を上書きするのを防ぐ。
+def select_non_blurb(tree)
+  tree.each_with_object({}) do |(key, value), acc|
+    if value.is_a?(Hash) && !value.empty?
+      child = select_non_blurb(value)
+      acc[key] = child unless child.empty? # 非表現値が残った枝だけ保持
+    elsif !value.is_a?(String) && !value.is_a?(Hash)
+      acc[key] = value # Array / Symbol / Integer / Float / true / false / nil
+    end
+  end
+end
+
+# locale ルートを持つ raw Hash（`{ "ja" => {...}, "en" => {...} }`）から、対象 prefix を全 locale で刈った
+# 新しい Hash を返す（非破壊）。移行漏れ検証のシミュレーションと実削除の両方で使う。
+def prune_prefix_all_locales(raw, locales, keys)
+  locales.reduce(raw) { |acc, locale| acc.merge(locale => prune_prefix(acc[locale] || {}, keys)) }
+end
+
+# ---- (1) 配置 ----
+out_path = options[:out]
+# Dir.glob は Ruby 3.0+ で昇順ソート済み（= Rails の i18n ロード順と同じ）を返す。
+original_files = Dir.glob(originals_glob)
+die("オリジナルが見つからない: #{originals_glob}") if original_files.empty?
+
+# locale ごとに merged サブツリーを構築する。{ "ja" => {...}, "en" => {...} } の形。
+# あるロケールに当該 prefix のキーが一つも無い（orig も export も空）場合は warn してスキップし、
+# 書き出し・検証から自然に除外する（複数ロケールでは「en は別 prefix しか持たない」等が正常に起こりうる）。
+merged_by_locale = {}
+LOCALES.each do |locale|
+  orig_sub = {}
+  original_files.each { |f| deep_merge!(orig_sub, extract_prefix(load_locale_tree(f, locale), prefix_keys)) }
+
+  exp_sub = extract_prefix(load_locale_tree(options[:export], locale), prefix_keys)
+
+  if orig_sub.empty? && exp_sub.empty?
+    warn("locale #{locale}: prefix '#{PREFIX}' のキーが無いためスキップ")
+    next
+  end
+
+  # orig がベース・export で上書き（String leaf は export 勝ち）し、最後に非表現値（非 String leaf）を
+  # orig 値で再適用して必ず勝たせる。export 側に壊れた非表現値（文字列化等）が出ても置換されない。
+  merged_by_locale[locale] = deep_merge(deep_merge(orig_sub, exp_sub), select_non_blurb(orig_sub))
+end
+
+# 全 locale でスキップ＝当該 prefix がどこにも存在しない（prefix の typo）。
+if merged_by_locale.empty?
+  die("prefix '#{PREFIX}' のキーが export にもオリジナルにも見つからない。prefix を確認すること。")
+end
+
+# ---- (2) 静的ガード（書き出し前にできる検証を先に。中途半端な --out を残さない）----
+# --out が次回起動時に Rails の i18n glob でロードされる場所か（採番ミス・配置ミスの検出）。
+# NOTE: I18n.load_path は runner 起動時に確定済みで、いま書き出す --out は含まれない。よって
+# 「現在の load_path に在るか」ではなく「Rails 標準 glob（config/locales/**/*.yml）に合致するか」を確認する。
+abs_out = File.expand_path(out_path)
+locales_root = File.expand_path('config/locales')
+unless abs_out.start_with?("#{locales_root}/") && abs_out.end_with?('.yml', '.yaml')
+  die("#{out_path} が config/locales 配下の .yml ではない。Rails の i18n ロード対象になる場所へ出力すること。")
+end
+
+# 全 leaf キーが regexp にマッチするか（regexp と prefix の不一致の早期検出）。leaf キーは locale を
+# 含まない（merged は locale ルート配下）ので、全 locale を同じ regexp で検証できる。
+merged_by_locale.each do |locale, merged|
+  non_matching = leaf_entries(merged).keys.grep_v(regexp)
+  next if non_matching.empty?
+
+  die("locale #{locale}: regexp #{regexp.inspect} にマッチしない leaf キーがある（regexp/prefix 不一致）:\n  #{non_matching.join("\n  ")}")
+end
+
+# 書き出し（ここまでの検証を通過してから）。merged_by_locale は { "ja" => {...}, "en" => {...} } 形なので
+# そのまま全 locale ルートを持つ YAML になる（スキップした locale は含まれない）。
+File.write(out_path, merged_by_locale.to_yaml)
+total_leaves = merged_by_locale.sum { |_locale, merged| leaf_entries(merged).size }
+puts "配置: #{out_path} （locale #{merged_by_locale.keys.join(',')} / leaf 合計 #{total_leaves} キー）"
+
+# YAML ラウンドトリップ（to_yaml → 再読込で各 locale の merged と一致するか）。
+merged_by_locale.each do |locale, merged|
+  die("YAML ラウンドトリップ不一致。書き出し結果が壊れている: #{out_path} (locale #{locale})") unless load_locale_tree(out_path, locale) == merged
+end
+
+# ---- (3) 移行漏れ検証（削除をメモリ上でシミュレート）----
+# 削除後に Rails がロードするであろう全 locales ツリーを実ロード順で再現する。
+#
+# NOTE: いま書き出した --out は起動時確定の I18n.load_path に含まれない（実機確認済み）。そのため
+# load_path 由来の既存ファイル群（gem の locale 含む）を実順で読みつつ、--out を**末尾に明示追加**して
+# 後勝ちさせ、「削除後＋移行分ロード済み」の状態を再現する。
+abs_out = File.expand_path(out_path)
+sim_paths = I18n.load_path.dup
+sim_paths << out_path unless sim_paths.map { |p| File.expand_path(p) }.include?(abs_out)
+original_abs = original_files.map { |f| File.expand_path(f) }
+
+sim_tree = {}
+sim_paths.each do |path|
+  next unless File.exist?(path)
+  next unless path.end_with?('.yml', '.yaml') # .rb ロードパスはこのスキルの範囲外（必要なら別途）
+
+  content = YAML.safe_load_file(path, permitted_classes: [Symbol], aliases: true) || {}
+  next unless content.is_a?(Hash)
+
+  # オリジナルからは対象 prefix を全 locale で刈った状態にする（実削除後と等価）。
+  content = prune_prefix_all_locales(content, LOCALES, prefix_keys) if original_abs.include?(File.expand_path(path))
+  deep_merge!(sim_tree, content)
+end
+
+sim = I18n::Backend::Simple.new
+sim_tree.each { |loc, data| sim.store_translations(loc, data) }
+
+# NOTE: missing 判定は `default:` センチネルで行う。`throw: true` は missing 時に Ruby の throw
+# （catch/throw フロー制御）で MissingTranslation を投げるため rescue では捕まらず UncaughtThrowError に
+# なる（実機確認済み）。default にユニークなオブジェクトを渡せば、missing のときだけそれが返る。
+# 空文字 "" は「存在」扱い（センチネルと equal? でないため missing 扱いしない）。
+missing = Object.new
+
+# 母集合は locale ごとに独立に取る（= その locale の merged の全 leaf キー）。locale 横断の和集合に
+# すると、en にしか無いキーを ja で lookup して誤検知する。各 locale はその locale に実在するキーだけ検証する。
+leaks = []
+merged_by_locale.each do |locale, merged|
+  leaf_entries(merged).each_key do |key|
+    value = sim.translate(locale.to_sym, key, default: missing)
+    leaks << [locale, key] if value.equal?(missing)
+  end
+end
+
+# ---- (4) ゲート ----
+unless leaks.empty?
+  warn "移行漏れ検出: 削除すると次の #{leaks.size} キーが未訳になる。オリジナルは変更していない。"
+  leaks.sort.each { |locale, key| warn "  - #{locale}: #{key}" }
+  die('中断。--out の内容・採番・regexp を確認すること。')
+end
+
+original_files.each do |f|
+  raw = YAML.safe_load_file(f, permitted_classes: [Symbol], aliases: true) || {}
+  File.write(f, prune_prefix_all_locales(raw, LOCALES, prefix_keys).to_yaml)
+end
+
+puts "削除: prefix '#{PREFIX}' をオリジナル #{original_files.size} ファイルから刈り取った。"
+puts '完了。手順7（local_first_key_regexp 追加）が未済なら次に実施すること。'

data/spec/copy_tuner_client/cache_spec.rb

@@ -34,6 +34,27 @@ describe 'CopyTunerClient::Cache' do
     expect(cache.queued.keys).to match_array(%w[en.test.key])
   end
 
+  it 'local_first_key_regexpにマッチするキー（locale除く）はアップロードキューに入れないこと' do
+    cache = build_cache(local_first_key_regexp: /\Aviews\./)
+    cache['ja.views.foo']    = 'local value'
+    cache['ja.messages.bar'] = 'copy tuner value'
+
+    cache.download
+
+    # 完全分離: views.* は copy_tuner へアップロードしない
+    expect(cache.queued.keys).to match_array(%w[ja.messages.bar])
+  end
+
+  it 'local_first_key_regexpがnil（デフォルト）の場合は全キーをアップロードすること' do
+    cache = build_cache(local_first_key_regexp: nil)
+    cache['ja.views.foo']    = 'local value'
+    cache['ja.messages.bar'] = 'copy tuner value'
+
+    cache.download
+
+    expect(cache.queued.keys).to match_array(%w[ja.views.foo ja.messages.bar])
+  end
+
   it '変更がない場合はアップロードしないこと' do
     cache = build_cache
     cache.flush

data/spec/copy_tuner_client/configuration_spec.rb

@@ -45,6 +45,7 @@ describe CopyTunerClient::Configuration do
   it { is_expected.to have_config_option(:middleware).overridable }
   it { is_expected.to have_config_option(:client).overridable }
   it { is_expected.to have_config_option(:cache).overridable }
+  it { is_expected.to have_config_option(:local_first_key_regexp).overridable.default(nil) }
 
   it 'should provide default values for secure connections' do
     config = CopyTunerClient::Configuration.new
@@ -189,6 +190,58 @@ describe CopyTunerClient::Configuration do
     expect(prefixed_logger).to be_a(CopyTunerClient::PrefixedLogger)
     expect(prefixed_logger.original_logger).to eq(logger)
   end
+
+  describe '#local_first_key?' do
+    let(:config) { CopyTunerClient::Configuration.new }
+
+    it 'returns false when local_first_key_regexp is nil (default)' do
+      expect(config.local_first_key?('views.foo.bar')).to eq false
+    end
+
+    context 'when local_first_key_regexp is set' do
+      before { config.local_first_key_regexp = /\Aviews\./ }
+
+      it 'returns true for a matching key' do
+        expect(config.local_first_key?('views.foo.bar')).to eq true
+      end
+
+      it 'returns false for a non-matching key' do
+        expect(config.local_first_key?('models.foo.bar')).to eq false
+      end
+
+      it 'returns false for a nil key' do
+        expect(config.local_first_key?(nil)).to eq false
+      end
+
+      it 'coerces a Symbol key before matching' do
+        expect(config.local_first_key?(:'views.foo')).to eq true
+      end
+    end
+  end
+
+  describe '#exclude_key_regexp= (deprecated)' do
+    let(:config) { CopyTunerClient::Configuration.new }
+    let(:deprecator) { instance_double(ActiveSupport::Deprecation, warn: nil) }
+
+    before { allow(ActiveSupport::Deprecation).to receive(:new).and_return(deprecator) }
+
+    it 'warns when a value is set' do
+      expect(deprecator).to receive(:warn).with(/exclude_key_regexp is deprecated/)
+
+      config.exclude_key_regexp = /\Aja\.views\./
+    end
+
+    it 'stores the assigned value' do
+      config.exclude_key_regexp = /\Aja\.views\./
+      expect(config.exclude_key_regexp).to eq(/\Aja\.views\./)
+    end
+
+    it 'does not warn when set to nil' do
+      expect(deprecator).not_to receive(:warn)
+
+      config.exclude_key_regexp = nil
+    end
+  end
 end
 
 shared_context 'stubbed configuration' do

data/spec/copy_tuner_client/copyray_spec.rb

@@ -54,5 +54,16 @@ describe CopyTunerClient::Copyray do
         it_behaves_like 'Not escaped'
       end
     end
+
+    context 'when the key matches local_first_key_regexp' do
+      let(:source) { 'Hello' }
+      let(:key) { 'views.foo' }
+
+      before { CopyTunerClient.configuration.local_first_key_regexp = /\Aviews\./ }
+
+      it 'does not inject the overlay marker' do
+        is_expected.to eq 'Hello'
+      end
+    end
   end
 end

data/spec/copy_tuner_client/helper_extension_spec.rb

@@ -23,4 +23,10 @@ describe CopyTunerClient::HelperExtension do
     view = KeywordArgumentsView.new
     expect(view.translate('some.key', name: 'World')).to eq '<!--COPYRAY some.key-->Hello, World'
   end
+
+  it 'does not inject the overlay marker for a local_first key' do
+    CopyTunerClient.configuration.local_first_key_regexp = /\Aviews\./
+    view = KeywordArgumentsView.new
+    expect(view.translate('views.foo', name: 'World')).to eq 'Hello, World'
+  end
 end

data/spec/copy_tuner_client/i18n_backend_spec.rb

@@ -427,4 +427,85 @@ describe 'CopyTunerClient::I18nBackend' do
       end
     end
   end
+
+  describe 'local_first_key_regexp（ローカル優先キー）' do
+    after { CopyTunerClient.configuration.local_first_key_regexp = nil }
+
+    # ローカル config/locales 相当のデータを I18n::Backend::Simple 側だけに格納する。
+    # I18nBackend#store_translations は cache にも書き込んでしまうため、
+    # Simple の store_translations を直接呼んでローカル YAML のみを再現する。
+    def store_local(backend, locale, data)
+      I18n::Backend::Simple.instance_method(:store_translations).bind(backend).call(locale, data)
+    end
+
+    # アップロード抑止（Cache#[]=）の検証用に、現在の configuration を反映した実 Cache を作る。
+    def build_real_cache
+      CopyTunerClient::Cache.new(FakeClient.new, CopyTunerClient.configuration.to_hash)
+    end
+
+    context 'local_first_key_regexp が nil（デフォルト）のとき' do
+      it 'views.* でも従来どおり copy_tuner（cache）を優先すること' do
+        CopyTunerClient.configuration.local_first_key_regexp = nil
+        cache['ja.views.foo'] = 'copy tuner value'
+        store_local(subject, :ja, views: { foo: 'local value' })
+
+        expect(subject.translate('ja', 'views.foo')).to eq('copy tuner value')
+      end
+    end
+
+    context 'local_first_key_regexp = /\Aviews\./ のとき' do
+      before { CopyTunerClient.configuration.local_first_key_regexp = /\Aviews\./ }
+
+      it 'views.* は cache に値があってもローカル YAML を優先すること' do
+        cache['ja.views.foo'] = 'copy tuner value'
+        store_local(subject, :ja, views: { foo: 'local value' })
+
+        expect(subject.translate('ja', 'views.foo')).to eq('local value')
+      end
+
+      it 'views.* 以外のキーは従来どおり copy_tuner を優先すること' do
+        cache['ja.messages.foo'] = 'copy tuner value'
+        store_local(subject, :ja, messages: { foo: 'local value' })
+
+        expect(subject.translate('ja', 'messages.foo')).to eq('copy tuner value')
+      end
+
+      it 'views.* がローカルにも cache にも無いとき nil を返し、空キー登録（アップロード）をしないこと' do
+        spy_cache = TestCache.new
+        allow(spy_cache).to receive(:[]=).and_call_original
+        backend = CopyTunerClient::I18nBackend.new(spy_cache)
+        I18n.backend = backend
+
+        result = backend.translate('ja', 'views.missing', default: nil)
+
+        expect(result).to be_nil
+        # 案1（完全分離）: local_first キーは空キー登録（アップロードキュー投入）を行わない
+        expect(spy_cache).not_to have_received(:[]=).with('ja.views.missing', nil)
+      end
+
+      it 'views.* を default: 付きで翻訳しても copy_tuner へアップロードしないこと' do
+        real_cache = build_real_cache
+        backend = CopyTunerClient::I18nBackend.new(real_cache)
+        I18n.backend = backend
+
+        result = backend.translate('ja', 'views.bar', default: 'literal default')
+
+        expect(result).to eq('literal default')
+        # 完全分離: local_first キーは default: 経由でもアップロードキューに入らない（Cache#[]= が弾く）
+        expect(real_cache.queued.keys).not_to include('ja.views.bar')
+      end
+
+      it 'store_translations 経由でも local_first キーはアップロードキューに入らないこと' do
+        real_cache = build_real_cache
+        backend = CopyTunerClient::I18nBackend.new(real_cache)
+        I18n.backend = backend
+
+        backend.store_translations(:ja, views: { foo: 'local value' }, messages: { bar: 'msg value' })
+
+        # 完全分離: views.* はキューに入らず、それ以外（messages.*）は従来どおり入る
+        expect(real_cache.queued.keys).not_to include('ja.views.foo')
+        expect(real_cache.queued.keys).to include('ja.messages.bar')
+      end
+    end
+  end
 end