copy_tuner_client 1.1.5 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 93652e0d1c83329df154658afb5d92a5ddeed5e7c417301ae0bc16d276cf3945
-  data.tar.gz: 02a2e3c38c136d258aec06ab2a1d4d60a05b21b441cbe4d8ad90767ab1786ab4
+  metadata.gz: 28fdccccf21b4d18bd14a1179edeb3f878dc38ccd4f79e30514255be98286f16
+  data.tar.gz: 9afc9b5073c5a3b0f02c004080294f87a78ca7ed6f478ae6d13baf0284df954c
 SHA512:
-  metadata.gz: ccd023595c35dd31542197803624dc52a93d5dabda5e49931b1d98f48406aef81fffe4a6131fa3538fa56375ae5b0247ee640ccfce8d174e1c6f46c7b5d35333
-  data.tar.gz: 5fee43f3ccb648e9410064bf63512a7ca1ee8d16b1358f5bd2f7383271fd3261ab714c3b5f28058829566f344243561b3fed2555541b999de9cacef85306288d
+  metadata.gz: 031e2d70ce76dd689f085c028f6c7be116f7988434f250efc88674fca5131a4e73b6bca57b65275cbe750500751e5f44a49a429d672878045c466a5335ead337
+  data.tar.gz: a88877b5bcc4c31eca6ce56f7d486525b92c8a2a62e37b177ce0937a9eb08525765a2022a2937413891c0231de8763d49381538b1cd1fe7b31c3fb8e6c10ea1e

data/CLAUDE.md

@@ -0,0 +1,32 @@
+# CLAUDE.md
+
+CopyTuner の Ruby クライアント gem。Rails アプリの I18n を CopyTuner サーバと同期する。
+
+## コマンド
+- テスト: `bundle exec rspec`（単一ファイル: `bundle exec rspec spec/copy_tuner_client/cache_spec.rb`）
+- 特定の Rails バージョンでテスト: `BUNDLE_GEMFILE=gemfiles/8.0.gemfile bundle exec rspec`
+- Lint: `bundle exec rubocop`（`sgcop` を継承）
+- フロントエンドビルド: `yarn build`（開発: `yarn dev`）
+- gem リリース: `bundle exec rake build|install|release`
+
+## アーキテクチャ
+`Configuration#apply`（lib/copy_tuner_client/configuration.rb）が全コンポーネントを組み立てる起点:
+- `Client` — CopyTuner サーバ / S3 との HTTP 通信
+- `Cache` — Mutex で保護された blurb ストア。Hash のように振る舞う。アップロードキューを管理
+- `I18nBackend` — デフォルトの I18n backend を置き換える（`I18n.backend = ...`）。lookup で Cache を参照
+- `Poller` / `ProcessGuard` — バックグラウンド同期スレッド
+- Rack middleware `RequestSync` / `CopyrayMiddleware` — 開発環境でのリクエスト毎同期とオーバーレイ
+Rails 統合は engine.rb のイニシャライザ経由（ヘルパー/SimpleForm フック、アセット precompile）。
+
+## Gotchas
+- **フロントエンドは `src/*.ts` を編集する。`app/assets/*` は Vite のビルド成果物なので直接編集しない**
+  （vite.config.ts が `src/main.ts` → `app/assets/javascripts/copytuner.js` を出力）。
+- キー除外の 2 オプションは混同しやすい:
+  - `exclude_key_regexp` — locale 付きキー対象・アップロード時に作用
+  - `local_first_key_regexp` — locale を除いたキー対象・lookup 時に作用（ローカル YAML 優先）
+  local_first キーのアップロード抑止は `Cache#[]=` に集約されている。
+- **アップロード抑止の新ルールは `Cache#[]=` に足す。`I18nBackend` の書き込み経路（`lookup` / `default` / `store_item`）ごとに個別ガードを足さない**
+  （理由: cache への書き込みは全経路が最終的に `Cache#[]=` を通る単一の関門。経路ごとにガードを足すと付け忘れの穴が生まれ、同じチェックが分散して保守負担になる。実際 local_first の抑止は当初 `default` 個別に足したが穴が残り、`Cache#[]=` への集約に作り直した）。
+
+## Claude Code スキル
+`skills/copy-tuner/` に i18n キー操作支援スキルがある（SKILL.md 参照）。

data/README.md

@@ -35,6 +35,48 @@ bundle exec rake copy_tuner:export
 
 これで、`config/locales/copy_tuner.yml` に翻訳ファイルが作成されます。
 
+## 特定のキーをローカル YAML 優先にする（段階移行）
+
+`config.local_first_key_regexp` を設定すると、**locale を除いたキー**（例 `views.foo.bar`）がその正規表現にマッチした場合、CopyTuner サーバのキャッシュをスキップして、ローカルの `config/locales/*.yml`（`I18n::Backend::Simple`）を優先的に参照します。
+
+```ruby
+CopyTunerClient.configure do |config|
+  # ...
+  # views.* で始まるキーはローカル YAML を優先する
+  config.local_first_key_regexp = /\Aviews\./
+end
+```
+
+CopyTuner で一元管理している翻訳を、`views.*` のような単位で段階的にローカル YAML へ移行するためのオプションです。
+
+- マッチしたキーは CopyTuner キャッシュを一切参照せず、ローカル YAML のみを引きます（完全分離）。
+- ローカル YAML にも存在しない場合は未訳（`nil` / MissingTranslation）となります。CopyTuner へのフォールバックや新規キーのアップロードは行いません。これにより移行漏れを未訳として検知できます。
+- マッチしたキーには、ビューヘルパー（`t` / `translate`）および SimpleForm のラベルで CopyRay オーバーレイマーカー（`<!--COPYRAY key-->`）を注入しません。これらのキーは CopyTuner 上で編集できないため、編集可能だと誤認させないためです。
+
+`exclude_key_regexp` との違い:
+
+| オプション | 対象 | 作用するタイミング |
+| --- | --- | --- |
+| `exclude_key_regexp` | locale 付きキー（例 `ja.views.foo`） | アップロード時（CopyTuner への送信を抑止） |
+| `local_first_key_regexp` | locale を除いたキー（例 `views.foo`） | 読み込み時（lookup の優先順位） |
+
+### `exclude_key_regexp` は非推奨です
+
+`exclude_key_regexp` は **非推奨**です（将来のリリースで削除予定）。設定すると deprecation 警告が出ます。代わりに `local_first_key_regexp` を使ってください。
+
+```ruby
+# Before（非推奨）
+config.exclude_key_regexp = /\Aja\.views\./
+
+# After: locale プレフィックス（ja.）を外して指定する
+config.local_first_key_regexp = /\Aviews\./
+```
+
+移行時の注意:
+
+- 対象キーの形式が異なります。`exclude_key_regexp` は **locale 付き**（`ja.views.foo`）、`local_first_key_regexp` は **locale を除いた**形式（`views.foo`）でマッチします。正規表現から locale プレフィックスを外してください。
+- 挙動も少し変わります。`exclude_key_regexp` はアップロードを抑止するだけで lookup 時は CopyTuner キャッシュを参照し続けますが、`local_first_key_regexp` は lookup 時に CopyTuner キャッシュをスキップしてローカル YAML を優先します（完全分離）。ローカル管理へ移行する用途では `local_first_key_regexp` のほうが適切です。
+
 ## Claude Code スキル
 
 `skills/copy-tuner/` に Claude Code 向けのスキルが含まれています。

data/lib/copy_tuner_client/cache.rb

@@ -21,6 +21,7 @@ module CopyTunerClient
       @logger = options[:logger]
       @mutex = Mutex.new
       @exclude_key_regexp = options[:exclude_key_regexp]
+      @local_first_key_regexp = options[:local_first_key_regexp]
       @upload_disabled = options[:upload_disabled]
       @ignored_keys = options.fetch(:ignored_keys, [])
       @ignored_key_handler = options.fetch(:ignored_key_handler, -> (e) { raise e })
@@ -51,6 +52,9 @@ module CopyTunerClient
 
       # NOTE: config/locales以下のファイルに除外キーが残っていた場合の対応
       key_without_locale = key.split('.')[1..].join('.')
+      # NOTE: local_first_key_regexp にマッチするキーは copy_tuner と完全分離するためアップロードしない
+      return if @local_first_key_regexp && key_without_locale.match?(@local_first_key_regexp)
+
       if @ignored_keys.include?(key_without_locale)
         @ignored_key_handler.call(IgnoredKey.new("Ignored key: #{key_without_locale}"))
       end

data/lib/copy_tuner_client/configuration.rb

@@ -18,7 +18,7 @@ module CopyTunerClient
                  proxy_port proxy_user secure polling_delay sync_interval
                  sync_interval_staging sync_ignore_path_regex logger
                  framework middleware disable_middleware disable_test_translation
-                 ca_file exclude_key_regexp s3_host locales ignored_keys ignored_key_handler
+                 ca_file exclude_key_regexp local_first_key_regexp s3_host locales ignored_keys ignored_key_handler
                  download_cache_dir].freeze
 
     # @return [String] The API key for your project, found on the project edit form.
@@ -114,7 +114,14 @@ module CopyTunerClient
     attr_accessor :poller
 
     # @return [Regexp] Regular expression to exclude keys.
-    attr_accessor :exclude_key_regexp
+    # @deprecated Use {#local_first_key_regexp} instead.
+    attr_reader :exclude_key_regexp
+
+    # @return [Regexp] Keys (without locale) matching this regexp bypass the
+    #   copy_tuner cache and are looked up from local config/locales
+    #   (I18n::Backend::Simple) first. Used for gradual migration from
+    #   copy_tuner to local YAML.
+    attr_accessor :local_first_key_regexp
 
     # @return [String] The S3 host to connect to (defaults to +copy-tuner-us.s3.amazonaws.com+).
     attr_accessor :s3_host
@@ -163,6 +170,7 @@ module CopyTunerClient
       self.html_escape = true
       self.ignored_keys = []
       self.ignored_key_handler = ->(e) { raise e }
+      self.local_first_key_regexp = nil
       self.project_id = nil
       self.download_cache_dir = Pathname.new(Dir.pwd).join('tmp', 'cache', 'copy_tuner_client')
 
@@ -314,6 +322,18 @@ module CopyTunerClient
       @api_key = api_key
     end
 
+    # @deprecated Use {#local_first_key_regexp} instead.
+    def exclude_key_regexp=(value)
+      unless value.nil?
+        ActiveSupport::Deprecation.new.warn(
+          'exclude_key_regexp is deprecated and will be removed in a future release. ' \
+          'Use local_first_key_regexp instead (note: it matches keys WITHOUT the locale prefix, ' \
+          'e.g. /\Aviews\./ instead of /\Aja\.views\./).'
+        )
+      end
+      @exclude_key_regexp = value
+    end
+
     # Sync interval for Rack Middleware
     def sync_interval
       if environment_name == 'staging'
@@ -336,6 +356,18 @@ module CopyTunerClient
       URI::Generic.build(scheme: self.protocol, host: self.host, port: self.port.to_i, path:).to_s
     end
 
+    # locale を除いたキーが local_first_key_regexp にマッチするかを返す。
+    # マッチするキーはローカル config/locales（CopyTuner 管理外）で管理されるため、
+    # オーバーレイマーカー注入やキャッシュ参照をスキップする必要がある。
+    #
+    # @param key_without_locale [String, Symbol, nil] locale prefix を除いたキー（例: "views.foo.bar"）
+    # @return [Boolean]
+    def local_first_key?(key_without_locale)
+      return false if local_first_key_regexp.nil? || key_without_locale.nil?
+
+      key_without_locale.to_s.match?(local_first_key_regexp)
+    end
+
     private
 
     def default_port

data/lib/copy_tuner_client/copyray.rb

@@ -7,6 +7,10 @@ module CopyTunerClient
     def self.augment_template(source, key)
       return source if source.blank? || !source.is_a?(String)
 
+      # NOTE: local_first（CopyTuner 管理外でローカル config/locales 優先）のキーには
+      # オーバーレイマーカーを出さない。編集できないキーを編集可能だと誤認させないため。
+      return source if CopyTunerClient.configuration.local_first_key?(key)
+
       escape = CopyTunerClient.configuration.html_escape && !source.html_safe?
       augmented = "<!--COPYRAY #{key}-->#{escape ? ERB::Util.html_escape(source) : source}"
       augmented.html_safe

data/lib/copy_tuner_client/i18n_backend.rb

@@ -73,6 +73,13 @@ module CopyTunerClient
         CopyTunerClient::configuration.ignored_key_handler.call(IgnoredKey.new("Ignored key: #{key_without_locale}"))
       end
 
+      # NOTE: local_first_key_regexp にマッチするキーは copy_tuner キャッシュをスキップし、
+      # ローカル config/locales（I18n::Backend::Simple）を優先する。段階的にローカルへ移行するための仕組み。
+      # ローカルに無い場合は nil（未訳）のまま返し、copy_tuner へのフォールバックも空キー登録も行わない（完全分離）。
+      if local_first_key?(key_without_locale)
+        return super
+      end
+
       # NOTE: ハッシュ化した場合に削除されるキーに対応するため、最初に完全一致をチェック（旧クライアントの動作を維持）
       # 例: `en.test.key` が `en.test.key.conflict` のように別のキーで上書きされている場合の対応
       exact_match = cache[key_with_locale]
@@ -134,6 +141,10 @@ module CopyTunerClient
       cache.wait_for_download
     end
 
+    def local_first_key?(key_without_locale)
+      CopyTunerClient.configuration.local_first_key?(key_without_locale)
+    end
+
     def default(locale, object, subject, options = {})
       content = super(locale, object, subject, options)
       return content if !object.is_a?(String) && !object.is_a?(Symbol)
@@ -141,6 +152,7 @@ module CopyTunerClient
       if content.respond_to?(:to_str)
         parts = I18n.normalize_keys(locale, object, options[:scope], options[:separator])
         # NOTE: ActionView::Helpers::TranslationHelper#translate wraps default String in an Array
+        # NOTE: local_first キーのアップロード抑止は Cache#[]= 側に集約している
         if subject.is_a?(String) || (subject.is_a?(Array) && subject.size == 1 && subject.first.is_a?(String))
           key = parts.join('.')
           cache[key] = content.to_str

data/lib/copy_tuner_client/translation_log.rb

@@ -13,6 +13,11 @@ module CopyTunerClient
     end
 
     def self.add(key, result)
+      # local_first（CopyTuner 管理外でローカル config/locales 優先）のキーは記録しない。
+      # ここに集約することで、Copyray オーバーレイの JSON（window.CopyTuner.data）にも
+      # local_first キーが混入しない。key は I18n.normalize_keys(nil, ...) 由来の locale なし形式。
+      return if CopyTunerClient.configuration.local_first_key?(key)
+
       translations[key] = result if initialized? && !translations.key?(key)
     end
 

data/lib/copy_tuner_client/version.rb

@@ -1,6 +1,6 @@
 module CopyTunerClient
   # Client version
-  VERSION = '1.1.5'.freeze
+  VERSION = '1.2.0'.freeze
 
   # API version being used to communicate with the server
   API_VERSION = '2.0'.freeze

data/skills/copy-tuner/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: copy-tuner
-description: copy_tuner を使った i18n キーの操作スキル。「翻訳キーを調べて」「i18nキーを追加して」「このテキストのキーは？」「i18nキーを探して」「翻訳を確認して」「copy_tunerで調べて」のような依頼に必ず使用する。新しい翻訳キーが必要な実装時、既存キーを参照する時、不要になったキーを処理する時にも積極的に使用する。
+description: "copy_tuner を使った i18n キーの操作スキル。「翻訳キーを調べて」「i18nキーを追加して」「このテキストのキーは？」「i18nキーを探して」「翻訳を確認して」「copy_tunerで調べて」のような依頼に必ず使用する。新しい翻訳キーが必要な実装時、既存キーを参照する時、不要になったキーを処理する時にも積極的に使用する。重要: config/locales ディレクトリや .yml 翻訳ファイルを読もうとしたとき・参照しようとしたときは、必ずこのスキルを使うこと。このプロジェクトの i18n は config/locales ではなく copy_tuner で管理されているため、config/locales を読んでも翻訳は見つからない。"
 license: MIT
 ---
 
@@ -25,10 +25,23 @@ license: MIT
 
 1. `search_key` で機能名・画面名を英語キーワードで検索し、命名パターンを把握する（例: `search_key("move_out")` で退去関連のキー名の構造を確認する）
 2. パターンに合わせたキー名を決める
-3. ja は必須。他に必要なロケールは `get_locales` で確認し、日本語以外は文脈に応じて翻訳して登録する
-4. コード内で `t("登録したキー名")` として使用する
+3. ja は必須。他に必要なロケールは `get_locales` で確認し、存在するロケール分を翻訳して登録する
+4. コード内で翻訳キーを使用する（`t` と `tt` の使い分けは「I18nメソッドの使い分け」セクション参照）
 
 ## 不要なキーの処理
 
 コード削除等で不要になったキーは削除せず `config/initializers/copy_tuner.rb` の `ignored_keys` に追加する。
 一定期間どこからも参照されていないことを確認してから手動削除する。
+
+## I18nメソッドの使い分け
+
+- **`t`メソッド**: 通常のテキスト出力に使用
+- **`tt`メソッド**: **HTML要素の属性値**に使用（必須）。copy_tuner_client gem の `HelperExtension` が提供するエイリアス。
+
+**理由**: CopyTunerの影響で `t` はHTMLコメント (`<!-- ... -->`) を埋め込みます。属性値に含まれると意図しない表示や動作不良の原因となります。
+
+```erb
+<div title="<%= tt('views.tooltips.help_text') %>">...</div>
+<input placeholder="<%= tt('views.forms.enter_name') %>">
+<h1><%= t('views.simulation.show.title') %></h1>
+```

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

data/spec/copy_tuner_client/translation_log_spec.rb

@@ -0,0 +1,51 @@
+require 'spec_helper'
+require 'copy_tuner_client/translation_log'
+
+describe CopyTunerClient::TranslationLog do
+  before { described_class.clear }
+
+  describe '.add' do
+    context 'when initialized' do
+      it 'records the key' do
+        described_class.add('views.foo', 'Hello')
+        expect(described_class.translations).to eq('views.foo' => 'Hello')
+      end
+
+      it 'does not overwrite an existing key' do
+        described_class.add('views.foo', 'Hello')
+        described_class.add('views.foo', 'World')
+        expect(described_class.translations['views.foo']).to eq 'Hello'
+      end
+
+      context 'when the key matches local_first_key_regexp' do
+        before { CopyTunerClient.configuration.local_first_key_regexp = /\Aviews\./ }
+
+        it 'does not record the matching key' do
+          described_class.add('views.foo', 'Hello')
+          expect(described_class.translations).to be_empty
+        end
+
+        it 'records keys that do not match' do
+          described_class.add('messages.greeting', 'Hi')
+          expect(described_class.translations).to eq('messages.greeting' => 'Hi')
+        end
+      end
+
+      context 'when local_first_key_regexp is not set' do
+        it 'records all keys' do
+          described_class.add('views.foo', 'Hello')
+          expect(described_class.translations).to eq('views.foo' => 'Hello')
+        end
+      end
+    end
+
+    context 'when not initialized' do
+      before { Thread.current[:translations] = nil }
+
+      it 'ignores the key' do
+        described_class.add('views.foo', 'Hello')
+        expect(described_class.initialized?).to be false
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: copy_tuner_client
 version: !ruby/object:Gem::Version
-  version: 1.1.5
+  version: 1.2.0
 platform: ruby
 authors:
 - SonicGarden
@@ -192,6 +192,7 @@ files:
 - ".ruby-version"
 - ".vscode/settings.json"
 - CHANGELOG.md
+- CLAUDE.md
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -239,6 +240,7 @@ files:
 - spec/copy_tuner_client/prefixed_logger_spec.rb
 - spec/copy_tuner_client/process_guard_spec.rb
 - spec/copy_tuner_client/request_sync_spec.rb
+- spec/copy_tuner_client/translation_log_spec.rb
 - spec/copy_tuner_client_spec.rb
 - spec/spec_helper.rb
 - spec/support/client_spec_helpers.rb