copy_tuner_client 1.1.5 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 93652e0d1c83329df154658afb5d92a5ddeed5e7c417301ae0bc16d276cf3945
-  data.tar.gz: 02a2e3c38c136d258aec06ab2a1d4d60a05b21b441cbe4d8ad90767ab1786ab4
+  metadata.gz: 70c29e81f0f1972e5b8833b0ab7a9f9b079186f055e7d988b207043930144708
+  data.tar.gz: 3277c0fc92c99421c183f19356ea49f8830df54c8bfdf2913c1433a4e30e6268
 SHA512:
-  metadata.gz: ccd023595c35dd31542197803624dc52a93d5dabda5e49931b1d98f48406aef81fffe4a6131fa3538fa56375ae5b0247ee640ccfce8d174e1c6f46c7b5d35333
-  data.tar.gz: 5fee43f3ccb648e9410064bf63512a7ca1ee8d16b1358f5bd2f7383271fd3261ab714c3b5f28058829566f344243561b3fed2555541b999de9cacef85306288d
+  metadata.gz: f7ca85e2ebd4d5f8634edc0a2b6c4ac1450d35c49e4bd81740c0bf31166ee8937c1cf29a4af4bda9ba5c1bf30d1985282635c9092a8ee2c6b931a0fcdb78c9f2
+  data.tar.gz: 680d69dcfee71fb565c08a948a41fae83946fd407045e50e4169266fdb83ef366dbb0c4a16326206ef1e7dae646e3d7a375bf98c88e3d5d8217bb1d755acbff4

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.1'.freeze
 
   # API version being used to communicate with the server
   API_VERSION = '2.0'.freeze

data/skills/copy-tuner/SKILL.md

@@ -1,34 +1,58 @@
 ---
 name: copy-tuner
-description: copy_tuner を使った i18n キーの操作スキル。「翻訳キーを調べて」「i18nキーを追加して」「このテキストのキーは？」「i18nキーを探して」「翻訳を確認して」「copy_tunerで調べて」のような依頼に必ず使用する。新しい翻訳キーが必要な実装時、既存キーを参照する時、不要になったキーを処理する時にも積極的に使用する。
+description: "このプロジェクトの i18n キー（翻訳）の参照・追加・更新・削除を行うスキル。i18n / 翻訳 / ロケール / `t` / `tt` / 翻訳キーに関わる操作のとき、および `config/locales` ディレクトリや `.yml` 翻訳ファイルを読む・参照する・編集するときは必ず使用すること。翻訳は原則 copy_tuner サーバで管理されており（一部キーのみ config/locales 管理）、素朴に config/locales を読むだけでは大半の翻訳が見つからず誤った判断をするため、必ずこのスキルの手順に従う。"
 license: MIT
 ---
 
 # copy_tuner スキル
 
-このプロジェクトの i18n は `config/locales` ではなく **copy_tuner** で管理している。
-キーの参照・登録・更新は copy_tuner MCP ツールで行う。
+このプロジェクトの i18n は原則 **copy_tuner** サーバで管理し、MCP ツールで操作する。
+例外として `local_first_key_regexp` にマッチするキーだけは `config/locales/*.yml` で管理される。
+**どちらの管理かを最初に判別する。**
 
-## 操作の判断
+## キーの管理場所の判別
 
-| やりたいこと | 使うツール |
+1. `config/initializers/copy_tuner.rb` の `local_first_key_regexp` を確認する（未設定なら全キー copy_tuner）。
+2. 対象キーから **locale を除いた形**（`ja.views.foo` → `views.foo`）がその正規表現にマッチするか見る。
+
+| 判別 | 管理場所 | 操作 |
+|---|---|---|
+| マッチする | config/locales（copy_tuner と完全分離） | `config/locales/*.yml` を Read / Edit |
+| マッチしない・未設定 | copy_tuner | MCP ツール（下記） |
+
+**config/locales 管理キーの落とし穴:**
+- copy_tuner には存在しないので、MCP ツールで探しても見つからない。`config/locales` を見ること。
+- copy_tuner に登録しても lookup でバイパスされ無効。必ず `.yml` 側に書く。
+- ja が無ければ未訳（`nil`）。copy_tuner にフォールバックしない（移行漏れを顕在化させる設計）。
+- prefix 単位の一括移行は別作業。必要なら `skills/copy-tuner-to-locales-migrate-prefix/` を使う。
+
+## copy_tuner MCP ツール
+
+| やりたいこと | ツール |
 |---|---|
-| キー名（または一部）から翻訳を調べる | `search_key` |
+| キー名（一部）から翻訳を調べる | `search_key`（引数は英語キーワード） |
 | 画面テキストからキーを逆引き | `search_translations` |
 | 新しいキーを登録する | `create_i18n_key` |
-| 既存キーの翻訳を更新する | `get_edit_url` でブラウザ編集 |
+| 既存キーの翻訳を更新する | `get_edit_url`（ブラウザ編集） |
 | 使用中ロケールを確認 | `get_locales` |
 
-> **使い分け**: キー名の一部（ドット区切りの名前空間など）が分かっているなら `search_key`（引数は英語のキーワード）。テキスト（日本語・英語の表示文言）しか分からないなら `search_translations`。命名パターンを調べたいときは両方試す。
+## 新規キー登録
 
-## 新規キー登録のフロー
-
-1. `search_key` で機能名・画面名を英語キーワードで検索し、命名パターンを把握する（例: `search_key("move_out")` で退去関連のキー名の構造を確認する）
-2. パターンに合わせたキー名を決める
-3. ja は必須。他に必要なロケールは `get_locales` で確認し、日本語以外は文脈に応じて翻訳して登録する
-4. コード内で `t("登録したキー名")` として使用する
+1. `search_key` で関連キーを検索し、既存の命名パターンに合わせる（例: `search_key("move_out")`）。
+2. ja は必須。他は `get_locales` で確認し、存在するロケール分を登録する。
 
 ## 不要なキーの処理
 
-コード削除等で不要になったキーは削除せず `config/initializers/copy_tuner.rb` の `ignored_keys` に追加する。
+削除せず `config/initializers/copy_tuner.rb` の `ignored_keys` に追加する。
 一定期間どこからも参照されていないことを確認してから手動削除する。
+
+## `t` と `tt` の使い分け
+
+**HTML 要素の属性値には `tt` を使う**（それ以外の通常出力は `t`）。`tt` は copy_tuner_client gem の
+`HelperExtension` が提供するエイリアス。`t` は CopyTuner の都合で HTML コメント (`<!-- ... -->`) を
+埋め込むため、属性値に入ると表示崩れや動作不良の原因になる。
+
+```erb
+<div title="<%= tt('views.tooltips.help_text') %>">...</div>
+<h1><%= t('views.simulation.show.title') %></h1>
+```

data/skills/copy-tuner-to-locales-cleanup/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: copy-tuner-to-locales-cleanup
+description: >-
+  copy_tuner（CopyTuner / copy_tuner_client）の全 i18n キーを config/locales へ prefix 単位で移行し終えた後、
+  gem・初期化子・CI・deploy・ドキュメント・MCP 設定を一括撤去して copy_tuner 依存を完全に取り除くスキル。
+  prefix 単位の移行は copy-tuner-to-locales-migrate-prefix スキルで先に完了させておくこと。
+disable-model-invocation: true
+---
+
+# copy_tuner 撤去スキル（クリーンアップ）
+
+`copy-tuner-to-locales-migrate-prefix` スキルで**全 prefix を config/locales へ移行し終えた後**に、
+1 回だけ実行する。`local_first_key_regexp` が全キーを覆っている（= もう CopyTuner から引かれるキーが無い）
+ことを確認してから、gem・初期化子・CI・deploy・ドキュメント・MCP 設定をまとめて撤去する。
+
+このスキルは**特定のリポジトリに依存しない**。固有値を覚えず、毎回リポジトリを探索して touchpoint を発見する。
+種別ごとの典型的な在処は `references/example-touchpoints.md` を参照。
+
+## なぜ完了判定を関門にするのか
+
+`local_first_key_regexp` でカバーできていない prefix が 1 つでも残ったまま gem を抜くと、その prefix のキーが
+config/locales に無く、**一斉に未訳化**する。だから「全キーが regexp にマッチしている」ことを gem 撤去前の
+**関門**にする。判定には gem 自身の `local_first_key?` を使い、export した全キーを 1 件ずつ通す。
+
+## ワークフロー
+
+### 1. 完了判定（関門）
+
+CopyTuner の全キーが `local_first_key_regexp` にマッチする（= 全 prefix 移行済み）ことを確認する。
+
+```bash
+# 全件 export（一時ファイルへ。読み取り専用検証だが export は書き込むので捨て場へ）
+bundle exec rake copy_tuner:export[tmp/copy_tuner_check.yml]
+```
+
+export YAML から locale を除いた全キーを取り出し、**gem の判定そのもの**で 100% マッチを確認する:
+
+```bash
+bin/rails runner '
+  require "yaml"
+  data = YAML.load_file("tmp/copy_tuner_check.yml")
+  locale = data.keys.first                      # 例: "ja"
+  keys = []
+  walk = ->(h, prefix) do
+    h.each do |k, v|
+      key = prefix.empty? ? k.to_s : "#{prefix}.#{k}"
+      v.is_a?(Hash) ? walk.call(v, key) : keys << key
+    end
+  end
+  walk.call(data[locale], "")
+  unmatched = keys.reject { |k| CopyTunerClient.configuration.local_first_key?(k) }
+  if unmatched.empty?
+    puts "OK: 全 #{keys.size} キーが local_first_key_regexp にマッチ。cleanup へ進める。"
+  else
+    puts "STOP: 未マッチ #{unmatched.size} 件（未移行 prefix が残存）。migrate-prefix へ戻る。"
+    puts unmatched.first(30)
+  end
+'
+```
+
+`STOP` が出たら **cleanup を中止し、`copy-tuner-to-locales-migrate-prefix` で残 prefix を移行してから出直す**。
+`OK` のときだけ次へ進む。
+
+> NOTE: ここで `export` を実行できるのは gem がまだ入っているから。完了判定は gem 撤去より**前**に行う。
+
+> 補助目印: migrate は prefix を移すたびにオリジナル（`0000_original_*.yml`）から該当サブツリーを削除するので、
+> 全移行完了時点で `0000_original_*.yml` はほぼ空（残るのは非表現値の隔離 `0005_rails_non_blurb.yml` 等のみ）に
+> なっているはず。`local_first_key?` のマッチ判定が主の関門で、ファイルが空かどうかは副次的な目視確認。
+> 食い違うとき（regexp は全マッチなのにオリジナルに blurb 化できるキーが残っている等）は削除漏れを疑う。
+
+### 2. 最終不正キーチェック
+
+gem を抜く前の最終ゲートとして、全キーに不正がないことを確認する。
+
+```bash
+bundle exec rake copy_tuner:detect_conflict_keys
+bundle exec rake copy_tuner:detect_html_incompatible_keys
+```
+
+両方が `All success` を出すこと。列挙された場合はそのキーが config/locales で壊れている可能性があるので、
+migrate-prefix 側で配置を直してから戻る。
+
+### 3. `tt` ヘルパーをアプリ側へ退避
+
+copy_tuner_client は `ActionView` の `translate` をフックする際に **`tt` という独自エイリアス**を生やす
+（copyray コメント注入なしの純粋な翻訳。シグネチャは `tt(key, **options)`）。アプリのビューが `tt(...)` を
+使っていると、gem 撤去で `tt` が消えて `NoMethodError`（テンプレートで未定義ヘルパー）になる。**gem を抜く前に**
+アプリ側へ移しておく。
+
+1. 利用箇所を洗い出す（残っていれば移行対象）:
+
+   ```bash
+   git grep -nw tt -- app lib | grep -v 'attr\|http\|setting'   # 単語境界で tt のみ。誤検出は目視で除外
+   ```
+
+2. アプリのヘルパー（`app/helpers/application_helper.rb` 等。全ビューから見える場所）に、**非推奨警告付きで
+   `t` に委譲するだけ**の `tt` を定義する。中身は `t` を呼ぶだけでよい（gem 撤去後は `translate` に copyray
+   コメントが付かないので、`tt` と `t` は実質同義になる）:
+
+   ```ruby
+   # NOTE: copy_tuner_client が生やしていた tt ヘルパーの後方互換。gem 撤去で未定義になるため退避した。
+   #       copyray コメント注入は廃止済みなので t と同義。新規コードでは t を使い、既存呼び出しは順次 t へ置換する。
+   def tt(key, **options)
+     ActiveSupport::Deprecation.new.warn('tt は非推奨です。t を使ってください。')
+     t(key, **options)
+   end
+   ```
+
+   > NOTE: `tt` はビューヘルパーなので、コントローラ等から呼んでいないか手順 1 で必ず確認する。ビュー専用なら
+   > `ApplicationHelper` でよいが、別 namespace のヘルパーでしか使われていない場合はそのスコープに合わせる。
+
+3. （任意・推奨）`tt(` を `t(` へ機械置換して呼び出し自体を消すと、非推奨ヘルパーを残さずに済む。置換する場合は
+   引数がそのまま通る（`tt(key, **options)` → `t(key, **options)`）。置換後は手順 1 の grep が 0 件になること。
+   置換しない場合は手順 2 のヘルパーを残し、警告ログで段階的に潰す。
+
+### 4. 初期化子と gem を撤去
+
+1. 初期化子（`config/initializers/copy_tuner.rb` 等）を削除（`local_first_key_regexp` ごと消える）。
+2. `Gemfile` から copy_tuner 系 gem（`copy_tuner_client`, `copy_tuner_client-mcp` 等）を削除。
+3. `bundle install` で `Gemfile.lock` を再生成。
+
+これで I18n バックエンドが gem 製（`CopyTunerClient::I18nBackend`）から Rails 標準に戻り、`t()` への
+copyray コメント注入も消える。あわせて `config/environments/*.rb` の `i18n.fallbacks` 等が gem に依存して
+いないか確認する（標準バックエンドでも挙動が変わらないこと）。
+
+### 5. CI を撤去
+
+リポジトリ探索で見つけた CI の copy_tuner 痕跡を削除する。典型的には:
+
+- copy_tuner 専用の deploy ワークフローファイル（main push で翻訳をデプロイする専用ファイル）… 丸ごと削除。
+- AI エージェント用ワークフローの `mcp__copy-tuner__*` allowedTools 許可 … 削除。
+- CI の「翻訳を export するステップ」… migrate-prefix の初回で削除済みのはず。**まだ残っていれば**ここで削除する
+  （`git grep copy_tuner .github/` で確認）。
+
+### 6. deploy / 起動スクリプトを撤去
+
+- deploy フックの `rake copy_tuner:deploy`（production 起動時に実行されるブロック）… 削除。
+- コンテナ起動スクリプトの `rake copy_tuner:export` フォールバック … **必ず削除**。
+  gem 撤去後はこのタスク自体が消えており、残すとコンテナ起動が `Don't know how to build task` で落ちる。取りこぼし注意。
+
+### 7. ドキュメント / スキル / MCP を撤去・方針最終化
+
+方針ドキュメントが「copy_tuner で管理」や「移行中」のまま残ると、将来の作業者や AI が矛盾した行動を取る。
+コードと方針を必ず揃える。
+
+- i18n 方針ドキュメント（`CLAUDE.md`・`doc/` 配下等）を **config/locales 管理に
+  最終化**する。migrate-prefix が残した「移行中」の中間記述を、「config/locales で管理。copy_tuner は廃止。
+  新規キーは config/locales へ追加。複数形化不要」に確定する。**モデル名・カラム名の例外規定も撤廃**する
+  （全キーがローカル化されたので例外は不要）。
+- copy_tuner 系スキル（`.claude/skills/` 配下の copy_tuner 操作スキル）を無効化または削除する。
+- `README.md` の copy_tuner リンク・補助ドキュメント（「copy_tuner サーバで i18n 管理」記述を持つコマンド定義等）
+  を修正する。
+- copy-tuner MCP server の接続設定（`.mcp.json` 等）を除去する。
+
+### 8. 最終検証
+
+`references/verification-final.md` の手順で、痕跡が残っていないか・gem が外れているか・テストが外部 API
+接続なしで通るか・未訳が出ないかを確認する。
+
+## 完了の目安
+
+- `git grep -i 'copy.tuner\|copytuner\|CopyTunerClient'`（vendor/tmp 除外）でアプリ側のヒットが無い。
+- 全翻訳キーが `config/locales` で解決し、`translation missing` が出ない。
+- テスト・Linter が通り、外部 API 接続なしで CI が完結する。
+- 方針ドキュメントが config/locales 管理に最終化され、「移行中」やモデル名・カラム名の例外記述が残っていない。

data/skills/copy-tuner-to-locales-cleanup/references/example-touchpoints.md

@@ -0,0 +1,111 @@
+# 典型的な touchpoint（種別ごと）
+
+copy_tuner（`copy_tuner_client` gem）を使う Rails アプリで、移行・撤去のときに触ることになる touchpoint を
+種別ごとに整理したもの。**探索クエリを投げるとこういう種類の結果が返る**というサンプルとして読む。値やパスは
+プロジェクトごとに違うので、これを暗記せず、SKILL.md 手順 1 の grep を必ず自分で走らせて発見すること。
+
+各 touchpoint に、どちらのスキルで触るかの印を付けた:
+
+- **[migrate]** = `copy-tuner-to-locales-migrate-prefix`（このスキル）で触る。prefix 移行のたびに編集。
+- **[cleanup]** = `copy-tuner-to-locales-cleanup`（全 prefix 完了後）で触る。gem・CI・deploy・docs・MCP 撤去。
+
+## 手順1の grep が見つける touchpoint（種別ごと）
+
+### gem 依存 — [cleanup]
+
+```ruby
+# Gemfile
+gem 'copy_tuner_client'                                              # 全環境
+gem 'copy_tuner_client-mcp', github: '<org>/copy_tuner_client-mcp',
+    require: false                                                    # development, test
+```
+
+> 段階移行の前提として、`copy_tuner_client` は **PR #110（local_first_key_regexp）入りバージョン**へ
+> 上げておく必要がある（migrate スキル手順 1 で確認）。
+
+### 初期化子 — [migrate]（local_first_key_regexp を積み上げる中心）
+
+`config/initializers/copy_tuner.rb`（パスはプロジェクトにより異なる）:
+
+```ruby
+CopyTunerClient.configure do |config|
+  config.api_key = Rails.application.credentials.fetch(:copytuner_api_key) { ENV.fetch('COPYTUNER_API_KEY', 'dummy') }
+  config.project_id = <プロジェクトの project_id>
+  config.host = '<copy_tuner サーバの host>'
+  config.html_escape = true
+  config.locales = [:ja]
+  config.ignored_keys = %w[]
+  # config.local_first_key_regexp = Regexp.union(/\Adevise\./, /\Aviews\./, ...)
+end
+```
+
+→ `html_escape` 運用・運用ロケールという前提が分割・非表現値の判断に効く。initializer 全体の削除は [cleanup]。
+
+### 既存 locales — [migrate]（先頭固定リネーム → 後ろへ配置 → オリジナルから削除）
+
+migrate スキルで既存 locales を `0000_original_` へ先頭固定リネームし、移行分を `0010_` 以降に置く
+（ロード順の後勝ちで export 側を正とする）。prefix を移行するたびにオリジナルから該当サブツリーを削除するため、
+全 prefix 完了後の cleanup 時点では **`0000_original_*.yml` はほぼ空**になっている。
+
+- `0000_original_*.yml`（既存・先頭固定） … 未移行 prefix の残り。全移行完了時点ではほぼ空。
+- `0010_` 以降の移行分 … prefix 単位で配置した YAML。Rails 標準フォーマットの非表現値（`date.abbr_day_names`
+  の配列・`date.order` のシンボル・`number.*.precision` の数値等）も migrate のスクリプトがこの中へ取り込んでいる。
+
+→ cleanup では空になったオリジナルの扱い（削除するか空のまま残すか）は任意。非表現値は移行分（`0010_` 以降）に
+取り込み済みで、gem 撤去後も Rails 標準フォーマットとして必要なので**消さない**。
+
+### CI — [migrate]（Export ステップのみ初回で削除） / [cleanup]（残り）
+
+- **CI の翻訳 export ステップ**（テストワークフロー内で `bin/rake copy_tuner:export` を走らせる類）…
+  「翻訳 DL 失敗でテストがコケないように」の保険。**[migrate] の初回で削除**（test が本番同等の
+  `cache.download` 挙動になる）。`disable_test_translation` は入れない。
+- **copy_tuner 専用の deploy ワークフロー**（main push で翻訳をデプロイする専用ファイル）…
+  **[cleanup] で丸ごと削除**。
+- **AI エージェント用ワークフローの `mcp__copy-tuner__*` allowedTools 許可** … **[cleanup] で削除**。
+
+### deploy / 起動スクリプト — [cleanup]
+
+- **deploy フック** … production 起動時に `bundle exec rake copy_tuner:deploy` を実行するブロック。削除。
+- **コンテナ起動スクリプト** … 起動時に `rake copy_tuner:export` を走らせるフォールバック。**gem 撤去後は
+  このタスク自体が消えて起動が `Don't know how to build task` で落ちる**ため、必ず削除する。取りこぼし注意。
+
+### 環境設定 — [cleanup] で確認
+
+`config/environments/production.rb` の `config.i18n.fallbacks = true` 等。標準バックエンドでも有効なので確認のみ。
+
+### ドキュメント / スキル / MCP — [migrate]（中間状態更新） / [cleanup]（最終化・撤去）
+
+- **i18n 方針ドキュメント**（`CLAUDE.md`・`doc/` 配下等）… 「copy_tuner サーバで i18n データを管理 /
+  config/locales 配下は利用しない / 新規キー登録は基本禁止」等の記述。**[migrate] で中間状態に更新**、
+  **[cleanup] で最終化**。上記を参照している他のドキュメント（`CLAUDE.md` 等）も連動。
+- **copy_tuner MCP 操作スキル**（`.claude/skills/` 配下）… **[cleanup] で無効化/削除**。
+- **補助ドキュメント** … 「多言語対応: copy_tuner サーバで i18n データを管理」のような記述を持つコマンド定義等。
+  **[cleanup] で修正**。
+- **`README.md`** … CopyTuner プロジェクトへのリンク。**[cleanup] で削除/修正**。
+- **`.mcp.json`** … copy-tuner MCP server 接続設定。**[cleanup] で削除**。
+
+## 規模感
+
+copy_tuner 側のキー数・export YAML の行数はプロジェクト次第だが、export YAML のトップには Rails i18n 慣習どおりの
+セクションが並ぶ: `activemodel.attributes` / `activerecord.{attributes,enums,models,errors}` / `views` / `text` /
+`helpers` / `date`/`time`/`datetime`/`number` / `devise` / `good_job` / `ice_cube` /
+`restrict_dependent_destroy` 等。これらのトップセクションが prefix 移行の基本粒度。`views` が最大になりやすいので
+最後に回す。
+
+## i18n 方針ドキュメント中間状態テンプレ（[migrate] 手順 10 で使う）
+
+移行中はこのような記述に置き換える。`<列挙>` は現在 `local_first_key_regexp` にマッチしている prefix に
+更新する（prefix を増やすたびに更新）。
+
+```markdown
+### 国際化（i18n）
+
+- **copy_tuner から config/locales へ段階移行中**
+- 以下の prefix は config/locales 管理へ移行済み（`local_first_key_regexp` にマッチ）: `<列挙: devise, ice_cube, views, ...>`
+- 上記以外の prefix はまだ copy_tuner サーバで管理
+- **新規キーの追加先**: 移行済み prefix のキーは config/locales へ。未移行 prefix のキーは従来どおり copy_tuner へ
+- 複数形化対応は不要（日本語環境）
+```
+
+> [cleanup] で全 prefix 完了後、この中間記述は「config/locales 管理。copy_tuner 廃止。新規キーは
+> config/locales へ。複数形化不要」に最終化する（モデル名・カラム名の例外規定も撤廃）。