copy_tuner_client 1.4.0 → 2.0.0

data/lib/copy_tuner_client/configuration.rb

@@ -10,7 +10,7 @@ require 'copy_tuner_client/copyray_middleware'
 
 module CopyTunerClient
   # Used to set up and modify settings for the client.
-  class Configuration
+  class Configuration # rubocop:disable Metrics/ClassLength
     # These options will be present in the Hash returned by {#to_hash}.
     OPTIONS = %i[api_key development_environments environment_name host
                  http_open_timeout http_read_timeout client_name client_url
@@ -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 local_first_key_regexp s3_host locales ignored_keys ignored_key_handler
+                 ca_file local_first_key_regexp s3_host locales ignored_keys ignored_key_handler
                  download_cache_dir].freeze
 
     # NOTE: Rails 標準ロケールで非文字列値（precision: Integer, significant: Boolean,
@@ -43,7 +43,8 @@ module CopyTunerClient
     attr_accessor :host
 
     # @return [Fixnum] The port on which your CopyTuner server runs (defaults to +443+ for secure connections, +80+ for insecure connections).
-    attr_accessor :port
+    # NOTE: reader は default_port フォールバック付きの明示定義（#port）があるため attr_accessor を使わない
+    attr_writer :port
 
     # @return [Boolean] +true+ for https connections, +false+ for http connections.
     attr_accessor :secure
@@ -94,7 +95,8 @@ module CopyTunerClient
     attr_accessor :polling_delay
 
     # @return [Integer] The time, in seconds, in between each sync to the server in development. Defaults to +60+.
-    attr_accessor :sync_interval
+    # NOTE: reader は environment で分岐する明示定義（#sync_interval）があるため attr_accessor を使わない
+    attr_writer :sync_interval
 
     # @return [Integer] The time, in seconds, in between each sync to the server in development. Defaults to +60+.
     attr_accessor :sync_interval_staging
@@ -128,10 +130,6 @@ module CopyTunerClient
 
     attr_accessor :poller
 
-    # @return [Regexp] Regular expression to exclude keys.
-    # @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
@@ -141,15 +139,12 @@ module CopyTunerClient
     # @return [String] The S3 host to connect to (defaults to +copy-tuner-us.s3.amazonaws.com+).
     attr_accessor :s3_host
 
-    # @return [Boolean] To disable Copyray comment injection, set true
+    # @return [Boolean] To disable Copyray marker injection, set true
     attr_accessor :disable_copyray_comment_injection
 
     # @return [Array<Symbol>] Restrict blurb locales to upload
     attr_accessor :locales
 
-    # @return [Boolean] Html escape
-    attr_accessor :html_escape
-
     # @return [Array<String>] A list of ignored keys
     attr_accessor :ignored_keys
 
@@ -165,7 +160,7 @@ module CopyTunerClient
     alias secure? secure
 
     # Instantiated from {CopyTunerClient.configure}. Sets defaults.
-    def initialize
+    def initialize # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
       self.client_name = 'CopyTuner Client'
       self.client_url = 'https://rubygems.org/gems/copy_tuner_client'
       self.client_version = VERSION
@@ -182,7 +177,6 @@ module CopyTunerClient
       self.upload_disabled_environments = %w[production staging]
       self.s3_host = 'copy-tuner.sg-apps.com' # NOTE: cloudfront host
       self.disable_copyray_comment_injection = false
-      self.html_escape = true
       self.ignored_keys = []
       self.ignored_key_handler = ->(e) { raise e }
       self.local_first_key_regexp = nil
@@ -197,7 +191,7 @@ module CopyTunerClient
     # @param [Symbol] option Key for a given attribute
     # @return [Object] the given attribute
     def [](option)
-      send(option)
+      public_send(option)
     end
 
     # Returns a hash of all configurable options
@@ -206,7 +200,7 @@ module CopyTunerClient
       base_options = { public: public?, upload_disabled: upload_disabled? }
 
       OPTIONS.inject(base_options) do |hash, option|
-        hash.merge option.to_sym => send(option)
+        hash.merge option.to_sym => public_send(option)
       end
     end
 
@@ -258,7 +252,10 @@ module CopyTunerClient
     # This creates the {I18nBackend} and puts them together.
     #
     # When {#test?} returns +false+, the poller will be started.
-    def apply
+    def apply # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      # NOTE: project_id は必須。未設定なら apply 時点で明示的に失敗させる
+      validate_project_id!
+
       self.locales ||= self.locales = if defined?(::Rails)
                                         ::Rails.application.config.i18n.available_locales.presence || Array(::Rails.application.config.i18n.default_locale)
                                       else
@@ -337,18 +334,6 @@ 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'
@@ -358,16 +343,11 @@ module CopyTunerClient
       end
     end
 
-    # @return [String] current project url by api_key
+    # @return [String] current project url by project_id
     def project_url
-      path =
-        if project_id
-          "/projects/#{project_id}"
-        else
-          ActiveSupport::Deprecation.new.warn('Please set project_id.')
-          "/projects/#{api_key}"
-        end
+      validate_project_id!
 
+      path = "/projects/#{project_id}"
       URI::Generic.build(scheme: self.protocol, host: self.host, port: self.port.to_i, path:).to_s
     end
 
@@ -389,6 +369,12 @@ module CopyTunerClient
 
     private
 
+    # project_id は必須。未設定なら明示的に失敗させる。
+    # apply（起動時の全体検証）と project_url（apply を経ない経路へのセーフネット）の両方から呼ぶ。
+    def validate_project_id!
+      raise ArgumentError, 'project_id is required' if project_id.nil?
+    end
+
     def default_port
       if secure?
         443

data/lib/copy_tuner_client/copyray/marker.rb

@@ -0,0 +1,24 @@
+module CopyTunerClient
+  class Copyray
+    # 訳文に埋め込むキーマーカーの可視テキストトークン。
+    # サーバ側（CopyrayMiddleware の Rewriter）だけが encode/scan/strip すればよく、
+    # フロントは data 属性化された後の DOM を見るので decode は不要。
+    #
+    # 例: encode('views.home.message') #=> "⟦CT:views.home.message⟧"
+    module Marker
+      # NOTE: 通常の本文・属性値に出現しない記号（U+27E6 / U+27E7）と固定プレフィックス CT: で
+      # 偶発衝突を二重に下げる。除去漏れても可読なので人間が原因に気づける（不可視文字は不採用）。
+      PREFIX = '⟦CT:'.freeze
+      SUFFIX = '⟧'.freeze
+
+      # NOTE: PREFIX/SUFFIX から動的構築し、区切り変更時に encode と SCAN_REGEXP がズレないようにする。
+      SCAN_REGEXP = /#{Regexp.escape(PREFIX)}(.*?)#{Regexp.escape(SUFFIX)}/
+
+      module_function
+
+      def encode(key)
+        "#{PREFIX}#{key}#{SUFFIX}"
+      end
+    end
+  end
+end

data/lib/copy_tuner_client/copyray/rewriter.rb

@@ -0,0 +1,113 @@
+require 'nokogiri'
+require 'copy_tuner_client/copyray/marker'
+
+module CopyTunerClient
+  class Copyray
+    # 完成 HTML を走査し、マーカートークンを含むテキストノードの親要素・属性値を持つ要素に
+    # data-copyray-key 属性を付与し、トークンを完全に除去する。
+    # CopyrayMiddleware の HTML 後処理（CSS/JS 挿入）の前段で呼ばれる。
+    module Rewriter
+      DATA_ATTR = 'data-copyray-key'.freeze
+
+      # NOTE: マーカーを含む巨大 HTML を Nokogiri で parse/traverse/再シリアライズすると
+      # サイズに比例して重くなる（実測 ~1MB で 167ms, ~3MB で 514ms）。development 限定機能で
+      # レスポンスを大きく悪化させないため、この閾値超では Nokogiri を通さず可視トークン除去のみ行う。
+      # 失うのは data-copyray-key（オーバーレイ編集導線）だけで、フォールバックの gsub は巨大ページでも数ms。
+      MAX_REWRITE_BYTESIZE = 1_000_000
+
+      class << self
+        # NOTE: 戻り値は [html, skipped]。skipped は data-copyray-key を付与できなかったことを表す
+        # （巨大DOMでのスキップ・Nokogiri 例外の双方で true）。ミドルウェアがこれを JS に伝え、
+        # オーバーレイ非対応である旨をツールバーで案内する。
+        def rewrite(html)
+          # NOTE: ボディが ASCII-8BIT に転落していると UTF-8 の Marker::PREFIX との include? 比較が
+          # Encoding::CompatibilityError を投げる（ミドルウェアのボディ連結で非ASCIIバイトを含む
+          # ASCII-8BIT チャンクが混じると発生）。実バイト列は本来 UTF-8 なので判定用に UTF-8 とみなす。
+          # String.new でエンコーディングだけ付け替える（元オブジェクトを破壊せずバッファもコピーしない）。
+          scannable = html.encoding == Encoding::UTF_8 ? html : String.new(html, encoding: Encoding::UTF_8)
+
+          # NOTE: マーカーが無ければ Copyray 無効時・マーカーの無い通常ページなので一切変形しない（高速パス）。
+          # これによりマーカー非注入の HTML は完全に無傷で、Nokogiri の正規化も通らない。
+          # （そもそも CopyrayMiddleware は development 限定で本番のスタックには登録されず、本番では呼ばれない。）
+          # 判定は正規表現より安い部分文字列検索で行う（プレフィックスがあれば必ずマーカー候補）。
+          return [html, false] unless scannable.include?(Marker::PREFIX)
+
+          # NOTE: 閾値超は Nokogiri を通さず可視トークン除去のみ。skipped=true で編集導線を諦めた旨を伝える。
+          return [strip_markers(scannable), true] if scannable.bytesize > MAX_REWRITE_BYTESIZE
+
+          [rewrite_with_nokogiri(scannable), false]
+        rescue StandardError => e
+          # NOTE: Copyray は開発支援機能なので、壊れた HTML 等で Nokogiri 処理が落ちても
+          # ページを 500 にしない。data-copyray-key 付与（編集導線）は諦め、最低限可視トークンだけ除去する。
+          warn_rewrite_failure(e)
+          [strip_markers(scannable), true]
+        end
+
+        private
+
+        # NOTE: gsub 対象が html ではなく scannable なのは、ASCII-8BIT のままだと UTF-8 の
+        # SCAN_REGEXP との比較で Encoding::CompatibilityError が再発しうるため。
+        def strip_markers(scannable)
+          scannable.gsub(Marker::SCAN_REGEXP, '')
+        end
+
+        def rewrite_with_nokogiri(scannable)
+          doc = Nokogiri::HTML(scannable)
+
+          doc.traverse do |node|
+            if node.text?
+              annotate_text_node(node)
+            elsif node.element?
+              annotate_attributes(node)
+            end
+          end
+
+          # NOTE: Nokogiri 走査はテキストノード親要素・属性値への属性付与とノード単位の除去を担うが、
+          # serialize 時の正規化（エンティティ復元等）でトークンが復活しうる縁を塞ぐため、
+          # 最終出力にもう一度 gsub をかけて残留トークンを保険で全除去する（可視トークンの除去漏れは画面に出るため）。
+          strip_markers(doc.to_html)
+        end
+
+        # NOTE: logger 未設定の構成でもフォールバック自体が落ちないよう nil ガードする。
+        def warn_rewrite_failure(error)
+          logger = CopyTunerClient.configuration.logger
+          logger&.warn("CopyTuner Copyray::Rewriter failed: #{error.class.name}: #{error.message}")
+        end
+
+        def annotate_text_node(node)
+          keys = scan_keys(node.content)
+          return if keys.empty?
+
+          set_keys(node.parent, keys)
+          node.content = node.content.gsub(Marker::SCAN_REGEXP, '')
+        end
+
+        def annotate_attributes(element)
+          element.attribute_nodes.each do |attr|
+            keys = scan_keys(attr.value)
+            next if keys.empty?
+
+            set_keys(element, keys)
+            attr.value = attr.value.gsub(Marker::SCAN_REGEXP, '')
+          end
+        end
+
+        # NOTE: 空キーは除く（JS 側も split 後に空要素を捨てるため、表現を両端で揃える）。
+        def scan_keys(text)
+          text.scan(Marker::SCAN_REGEXP).flatten.reject(&:empty?)
+        end
+
+        # NOTE: 同一テキストノード／属性値に複数マーカーが連結されると全キーをここで受け取り、
+        # 1 要素に複数キーをカンマ区切りで保持する（1 要素 1 キーだと 2 個目以降の編集導線が消える）。
+        # 既存値がある場合（同じ要素を複数経路で踏むケース）はマージして重複排除し、出現順を保つ。
+        # I18n キーに ',' は通常含まれないため区切り文字として安全。JS 側もカンマ区切りを前提に読む。
+        def set_keys(element, keys)
+          return if element.nil? || !element.element?
+
+          existing = element[DATA_ATTR]&.split(',') || []
+          element[DATA_ATTR] = (existing + keys).uniq.join(',')
+        end
+      end
+    end
+  end
+end

data/lib/copy_tuner_client/copyray.rb

@@ -1,9 +1,12 @@
+require 'copy_tuner_client/copyray/marker'
+
 module CopyTunerClient
   class Copyray
     # This:
     #   message
     # Becomes:
-    #   <!--COPYRAY views.home.index.message-->message
+    #   ⟦CT:views.home.index.message⟧message
+    # マーカートークンは CopyrayMiddleware の Rewriter で data-copyray-key 属性に変換され、HTML から除去される。
     def self.augment_template(source, key)
       return source if source.blank? || !source.is_a?(String)
 
@@ -11,9 +14,13 @@ module CopyTunerClient
       # オーバーレイマーカーを出さない。編集できないキーを編集可能だと誤認させないため。
       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
+      # NOTE: マーカーは平文・html_safe どちらの訳文にも埋め込む（画面に出る全テキストをオーバーレイ対象にする）。
+      # トークンの区切り記号 ⟦⟧ は HTML 特殊文字ではないため、平文が ActionView でエスケープされても無傷で残り、
+      # Rewriter の走査は崩れない。
+      # html_safe フラグは source のものを引き継ぐ。html_safe を勝手に立てると平文訳文の本体（& < >）が
+      # エスケープされず XSS になり、逆に html_safe を落とすと _html 訳文がエスケープされて壊れるため。
+      augmented = Marker.encode(key) + source
+      source.html_safe? ? augmented.html_safe : augmented
     end
   end
 end

data/lib/copy_tuner_client/copyray_middleware.rb

@@ -1,5 +1,7 @@
 # cf) xray-rails : xray/middleware.rb
 
+require 'copy_tuner_client/copyray/rewriter'
+
 module CopyTunerClient
   class CopyrayMiddleware
     def initialize(app)
@@ -11,8 +13,13 @@ module CopyTunerClient
       status, headers, response = @app.call(env)
       if html_headers?(status, headers) && body = response_body(response)
         csp_nonce = env['action_dispatch.content_security_policy_nonce'] || env['secure_headers_content_security_policy_nonce']
+        # NOTE: CSS/JS 挿入の前に Rewriter を通す。serialize 後も </body> は必ず出力されるので
+        # append_to_html_body の rindex は機能し、CSS/JS タグはトークン非含有なので二重処理も起きない。
+        # NOTE: skipped は data-copyray-key を付与できなかったこと（巨大DOM/Nokogiri例外）を表す。
+        # JS にこれを伝え、オーバーレイ非対応である旨をツールバーで案内させる。
+        body, skipped = CopyTunerClient::Copyray::Rewriter.rewrite(body)
         body = append_css(body, csp_nonce)
-        body = append_js(body, csp_nonce)
+        body = append_js(body, csp_nonce, skipped: skipped)
         content_length = body.bytesize.to_s
         headers['Content-Length'] = content_length
         # maintains compatibility with other middlewares
@@ -37,7 +44,7 @@ module CopyTunerClient
       append_to_html_body(html, css_tag)
     end
 
-    def append_js(html, csp_nonce)
+    def append_js(html, csp_nonce, skipped: false)
       json =
         if CopyTunerClient::TranslationLog.initialized?
           CopyTunerClient::TranslationLog.translations.to_json
@@ -49,6 +56,7 @@ module CopyTunerClient
         window.CopyTuner = {
           url: '#{CopyTunerClient.configuration.project_url}',
           data: #{json},
+          keysSkipped: #{skipped},
         }
       SCRIPT
       append_to_html_body(html, helpers.javascript_include_tag('copytuner', type: 'module', crossorigin: 'anonymous', nonce: csp_nonce))

data/lib/copy_tuner_client/helper_extension.rb

@@ -17,6 +17,12 @@ module CopyTunerClient
               I18n.t(key.to_s.first == '.' ? scope_key_by_partial(key) : key, **options)
             end
 
+            # NOTE: マーカーは HTML コメントとしてブラウザに無視されつつ Copyray オーバーレイのキー特定に
+            # 使われる。HTML 以外の経路（メール本文・render :json・CSV/PDF など）ではコメントが文字列として
+            # 出力に混入してしまうため、それらの経路には注入しない。default 引数による初期値登録は維持する
+            # 必要があるため、このガードは初期値登録（上の I18n.t 呼び出し）より後に置く。
+            return source unless copyray_injectable?
+
             if CopyTunerClient.configuration.disable_copyray_comment_injection
               source
             else
@@ -32,13 +38,28 @@ module CopyTunerClient
               CopyTunerClient::Copyray.augment_template(source, scope_key)
             end
           end
+
+          # NOTE: HTML 以外の経路（メール本文・render :json・CSV/PDF など）ではマーカーが文字列として
+          # 出力に混入するため注入しない。判定には controller.request.format を使い、@current_template.format /
+          # lookup_context.formats のような ActionView の内部実装には依存させない（Rails バージョン間で壊れうるため）。
+          def copyray_injectable?
+            current_controller = controller
+            return false if current_controller.nil?
+
+            # NOTE: mailer は request を持たず request.format で判定できない。かつメール本文への
+            # マーカー混入は実害が大きいため、controller の型で明示除外する。
+            return false if defined?(ActionMailer::Base) && current_controller.is_a?(ActionMailer::Base)
+
+            # NOTE: request が無い／format が html でない経路には注入しない。&. と || false で
+            # request 不在時も安全に false を返す。
+            current_controller.request&.format&.html? || false
+          end
+          private :copyray_injectable?
+
           if middleware_enabled
             alias_method :translate_without_copyray_comment, :translate
             alias_method :translate, :translate_with_copyray_comment
             alias :t :translate
-            alias :tt :translate_without_copyray_comment
-          else
-            alias :tt :translate
           end
         end
       end

data/lib/copy_tuner_client/i18n_backend.rb

@@ -26,18 +26,11 @@ module CopyTunerClient
     #
     # @return [Object] the translated key (usually a String)
     def translate(locale, key, options = {})
-      # I18nの標準処理に任せる（内部でlookupが呼ばれる）
-      content = super
-
-      return content if content.nil? || content.is_a?(Hash)
-
-      # HTML escapeの処理（ツリー構造のHashは除く）
-      if CopyTunerClient.configuration.html_escape
-        content
-      else
-        # Backward compatible
-        content.respond_to?(:html_safe) ? content.html_safe : content
-      end
+      # I18nの標準処理に任せる（内部でlookupが呼ばれる）。
+      # NOTE: html_safe 化は backend では行わない。.html/_html キーの html_safe 化は
+      # ActionView の TranslationHelper（ActiveSupport::HtmlSafeTranslation）が担うため、
+      # backend は I18n 標準どおり素の content を返すだけにする（旧 html_escape 分岐は廃止）。
+      super
     end
 
     # Returns locales available for this CopyTuner project.

data/lib/copy_tuner_client/version.rb

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

data/skills/copy-tuner/SKILL.md

@@ -71,13 +71,44 @@ license: MIT
 削除せず `config/initializers/copy_tuner.rb` の `ignored_keys` に追加する。
 一定期間どこからも参照されていないことを確認してから手動削除する。
 
-## `t` と `tt` の使い分け
+## 翻訳ヘルパー（`t`）
 
-**HTML 要素の属性値には `tt` を使う**（それ以外の通常出力は `t`）。`tt` は copy_tuner_client gem の
-`HelperExtension` が提供するエイリアス。`t` は CopyTuner の都合で HTML コメント (`<!-- ... -->`) を
-埋め込むため、属性値に入ると表示崩れや動作不良の原因になる。
+**通常出力・属性値ともに `t`（`translate`）を使う。** 属性値も含めて区別は不要。
+
+**`tt` は削除済み。** PR #122 で存在理由を喪失したため削除した。既存の `tt` 呼び出しは `t` へ置き換える（属性値含め）。
+
+## 落とし穴: 開発環境で訳文にマーカートークンが混入する
+
+PR #122 の可視トークン方式では、development（`middleware` 有効時）の `t('key')` の戻り値は
+`⟦CT:key⟧訳文本体`（記号は U+27E6 / U+27E7）のように、訳文先頭に Copyray マーカートークンが付いた
+文字列になる。トークンは配信直前に `CopyrayMiddleware` → `Rewriter` が `data-copyray-key` 属性へ変換
+して HTML から完全除去するため画面表示は正常だが、**ビューで訳文を文字列として加工するコードは、
+除去前のトークン込み文字列に作用してしまう。**
+
+**本番では再現しない。** 本番では `CopyrayMiddleware` 自体が登録されずマーカー注入もされないため、
+戻り値は素の訳文。**開発環境だけ挙動が違う**のが見落としやすい点。
+
+危険なコード例:
+
+```erb
+<%= truncate(t('views.foo.body')) %>   <%# ⟦CT:...⟧ 込みの長さで切られ、トークン途中で切れる／本文が短く切られる %>
+<%= t('views.foo.title').length %>     <%# トークン長が加算され想定外の値になる %>
+```
+
+一般化すると、`t(...)` の戻り値を `truncate` / `length` / スライス（`[0..n]`）/ 正規表現マッチ /
+文字数バリデーション等で**文字列処理する全般**が対象。
+
+**対処**: 訳文を文字列加工する場合、マーカーを注入しない `I18n.t`（`translate` ヘルパーではなく
+`I18n` モジュールを直接呼ぶ）で訳文を取得してから加工する。`I18n.t` は HelperExtension のラッパーを
+通らないためトークンが付かない。
 
 ```erb
-<div title="<%= tt('views.tooltips.help_text') %>">...</div>
-<h1><%= t('views.simulation.show.title') %></h1>
+<%= truncate(I18n.t('views.foo.body')) %>
 ```
+
+注意:
+- `I18n.t` は partial 相対キー（先頭ドットの `t('.body')`）を解決しないので、`I18n.t('views.foo.body')`
+  のように**絶対キーで書く**こと。
+
+**このスキルでの注意**: キー追加・参照・コード差し替えを行う際、上記のように訳文を文字列加工して
+いるコードを書く／触る場合はこの罠を念頭に置くこと。

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

@@ -82,10 +82,10 @@ migrate-prefix 側で配置を直してから戻る。
 
 ### 3. `tt` ヘルパーをアプリ側へ退避
 
-copy_tuner_client は `ActionView` の `translate` をフックする際に **`tt` という独自エイリアス**を生やす
-（copyray コメント注入なしの純粋な翻訳。シグネチャは `tt(key, **options)`）。アプリのビューが `tt(...)` を
-使っていると、gem 撤去で `tt` が消えて `NoMethodError`（テンプレートで未定義ヘルパー）になる。**gem を抜く前に**
-アプリ側へ移しておく。
+copy_tuner_client はかつて `ActionView` の `translate` をフックする際に **`tt` という独自エイリアス**を生やして
+いた（シグネチャは `tt(key, **options)`）。PR #122 で存在理由を喪失したため gem からは削除済みだが、過去の
+copy_tuner_client を使っていたアプリのビューに `tt(...)` 呼び出しが残っていると `NoMethodError`（テンプレートで
+未定義ヘルパー）になる。**gem を抜く前に**アプリ側へ移しておく（既に gem 側に `tt` が無い場合も手順は同じ）。
 
 1. 利用箇所を洗い出す（残っていれば移行対象）:
 

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

@@ -60,13 +60,8 @@ config.local_first_key_regexp = Regexp.union(
 （`/\Aviews\./`。`Regexp.union` に文字列を渡す場合は自動エスケープされるが、Regexp リテラルを渡すときは自分で
 書く）。
 
-## deprecated な exclude_key_regexp との違い
+## 旧 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 ごと撤去される。
+かつて存在した `exclude_key_regexp` オプションは v2 で削除済み。`local_first_key_regexp` を使うこと
+（対象は locale を**除いた**キー `views.foo`、lookup 時に作用しローカル YAML を優先＝完全分離）。
+既存 initializer に `exclude_key_regexp` の設定が残っている場合は削除する。