inertia_i18n 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b68ed790e8d127e23f0b40c11bc74747a92a7075ba09474d4e670fa82ff558c
-  data.tar.gz: 73eefa0cf481919637be088a6ad9a483e22ad101fb15803d3f28f10e5d96d302
+  metadata.gz: 34e9a2d18070430f9210ad477789b8d179c7feb234d9de11f5a6358ce4eda012
+  data.tar.gz: 95bb612b926a1a9eaf6b7cbe2d86fb53dfd06dcc62d9b8d7be8f7a70c5a66057
 SHA512:
-  metadata.gz: 5b8ffe3ede9a8673882e941e98e822f2afbb6d5f10f48b7ffb83ad538ac4432a5bcd57ccb4ea37ce5c988d1983af1a4f478164a76861e82fea735afeaa37a879
-  data.tar.gz: a47098ba92a0f0c812e0e1632e6a9113b5f5b5b78600f3d0beb04680d684542557fe6fc4d5d0230ef06408c1342d636f8d654665568810b96fabe3fa85c000d7
+  metadata.gz: 2ac2dc6afe2112afdb8cac7a14a11b55880964d0ea86aab494fbb31350096ce502caa64b28b7b9570faa3d833cdadb8b7c1be3a4f95cb382d065c91244103954
+  data.tar.gz: 62a53052bfb31864001da174ed667ad6fbdab6d36461b47726e373515a621c7c98d8d45d68ee7dd82931f0d7373acf920c1a967230f6383624c09e0b48888029

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 ## [Unreleased]
 
+## [0.6.0] - 2026-02-09
+
+### Added
+
+- **Context Awareness**: `missing` and `unused` commands now report the file path and line number where the key was found (e.g., `app/frontend/User.vue:42`).
+- **Magic Comments**: Support for `// inertia-i18n-use key.name` and `/* inertia-i18n-use key.name */` to mark dynamic keys as used.
+- **i18n-tasks Compatibility**:
+    - Support for `// i18n-tasks-use key.name` comments (interoperability).
+    - `InertiaI18n::I18nTasks::Scanner` adapter class to allow `i18n-tasks` to use `inertia_i18n`'s frontend scanning logic.
+- **Robust CLI**: `inertia-i18n` command now correctly loads the library in non-Rails environments.
+
+### Fixed
+
+- Scanner adapter now returns data in the format `i18n-tasks` expects (including source location).
+
 ## [0.5.0] - 2026-02-06
 
 ### Added

data/README.md

@@ -231,6 +231,16 @@ Handles:
 - Template literals: `t(\`user.\${type}.title\`)` (flagged for review)
 - Dynamic patterns: `t(keyVariable)` (flagged for review)
 
+### Magic Comments
+
+Use magic comments to mark dynamic keys as used or suppress warnings. Both `inertia-i18n-use` and `i18n-tasks-use` are supported.
+
+```javascript
+// inertia-i18n-use status.active
+// inertia-i18n-use status.inactive
+const statusLabel = t(`status.${status}`)
+```
+
 ### Health Checks
 
 | Check            | Description                                      |
@@ -328,7 +338,26 @@ jobs:
 
 ## Compatibility with i18n-tasks
 
-If you use [i18n-tasks](https://github.com/glebm/i18n-tasks) for your backend translations, it might flag your frontend keys as "unused" or "missing". To prevent this, configure `i18n-tasks` to ignore the frontend locale directory.
+InertiaI18n works seamlessly with [i18n-tasks](https://github.com/glebm/i18n-tasks).
+
+### 1. Integrating Scanners (Recommended)
+
+You can configure `i18n-tasks` to use the `inertia_i18n` scanner. This allows `i18n-tasks` to correctly detect frontend key usage, so you can use `i18n-tasks unused` for your entire project (backend + frontend).
+
+Add this to your `config/i18n-tasks.yml`:
+
+```yaml
+<% require 'inertia_i18n/i18n_tasks/scanner' %>
+search:
+  scanners:
+    - InertiaI18n::I18nTasks::Scanner
+```
+
+Now `i18n-tasks` will "see" keys used in your Vue/React/Svelte files.
+
+### 2. Separating Concerns
+
+If you prefer to keep them separate, configure `i18n-tasks` to ignore the frontend locale directory so it doesn't flag frontend keys as "unused" or "missing".
 
 Add this to your `config/i18n-tasks.yml`:
 

data/exe/inertia-i18n

@@ -11,6 +11,7 @@ if File.exist?("config/environment.rb")
   require File.expand_path("config/environment.rb")
 end
 
+require "inertia_i18n"
 require "inertia_i18n/cli"
 
 InertiaI18n::Cli.start(ARGV)

data/lib/inertia_i18n/cli.rb

@@ -363,7 +363,20 @@ module InertiaI18n
       if verbose
         issues.each do |issue|
           puts "  - #{issue[:key]}"
+          if issue[:occurrences]&.any?
+            issue[:occurrences].each do |loc|
+              puts "    ↳ #{loc[:file]}:#{loc[:line]}"
+            end
+          end
         end
+      else
+        # In non-verbose mode, show first occurrence for context
+        issues.take(5).each do |issue|
+          loc = issue[:occurrences]&.first
+          loc_str = loc ? " (#{loc[:file]}:#{loc[:line]})" : ""
+          puts "  - #{issue[:key]}#{loc_str}"
+        end
+        puts "  ... and #{issues.count - 5} more (use --verbose to see all)" if issues.count > 5
       end
       puts
     end

data/lib/inertia_i18n/health_checker.rb

@@ -52,10 +52,19 @@ module InertiaI18n
       missing = filter_ignored_keys(missing, @config.ignore_missing)
 
       missing.each do |key|
+        locations = @scan_results.occurrences[key]
+        message = "Key '#{key}' is used in code but missing from #{primary_locale}.json"
+
+        if locations&.any?
+          first_loc = locations.first
+          message += " (found in #{first_loc[:file]}:#{first_loc[:line]})"
+        end
+
         @issues[:missing] << {
           key: key,
           severity: :error,
-          message: "Key '#{key}' is used in code but missing from #{primary_locale}.json"
+          message: message,
+          occurrences: locations
         }
       end
     end

data/lib/inertia_i18n/i18n_tasks/scanner.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "i18n/tasks/scanners/file_scanner"
+require "i18n/tasks/scanners/results/occurrence"
+
+module InertiaI18n
+  module I18nTasks
+    class Scanner < ::I18n::Tasks::Scanners::FileScanner
+      def scan_file(path)
+        # Scan file using InertiaI18n logic
+        scanner = InertiaI18n::Scanner.new
+        parser = scanner.parser_for_file(path)
+        return [] unless parser
+        return [] if parser.instance_of?(InertiaI18n::Parsers::BaseParser)
+
+        # Extract keys: {static: [{key: 'foo', line: 1}], dynamic: [...]}
+        results = parser.extract_keys(path)
+
+        # Convert to i18n-tasks format: [ [key, Occurrence] ]
+        results[:static].map do |usage|
+          key = usage[:key]
+
+          # Return the format i18n-tasks expects for key occurrences
+          [
+            key,
+            ::I18n::Tasks::Scanners::Results::Occurrence.new(
+              path: path,
+              line_num: usage[:line],
+              pos: 1,
+              line_pos: 1,
+              line: "",
+              raw_key: key
+            )
+          ]
+        end
+      end
+    end
+  end
+end

data/lib/inertia_i18n/parsers/javascript_parsing.rb

@@ -9,11 +9,33 @@ module InertiaI18n
 
       def extract_javascript_keys(content)
         {
-          static: extract_static_keys(content).uniq,
+          static: (extract_static_keys(content) + extract_magic_comments(content)).uniq { |k| k[:key] },
           dynamic: extract_dynamic_patterns(content).uniq { |p| p[:pattern] }
         }
       end
 
+      def extract_magic_comments(content)
+        keys = []
+
+        # Regex to match both 'inertia-i18n-use' and 'i18n-tasks-use'
+        # Group 1: key
+        comment_pattern = /(?:inertia-i18n-use|i18n-tasks-use)\s+([a-zA-Z0-9_.]+)/
+
+        # Single line comments: // inertia-i18n-use key.name
+        content.scan(%r{//\s*#{comment_pattern}}) do |match|
+          line = content[0..Regexp.last_match.begin(0)].count("\n") + 1
+          keys << {key: match[0], line: line}
+        end
+
+        # Block comments: /* inertia-i18n-use key.name */
+        content.scan(%r{/\*\s*#{comment_pattern}\s*\*/}) do |match|
+          line = content[0..Regexp.last_match.begin(0)].count("\n") + 1
+          keys << {key: match[0], line: line}
+        end
+
+        keys
+      end
+
       def extract_static_keys(content)
         keys = []
 
@@ -23,25 +45,22 @@ module InertiaI18n
           escaped_func = Regexp.escape(func)
 
           # Matches t('key'), t("key"), t(`key`)
-
-          # Uses a lookahead to ensure it's a translation function call
-          # Uses lookbehind (?<![\w]) to ensure we don't match end of other words (e.g. split)
           content.scan(/(?<!\w)#{escaped_func}\(\s*(['"`])([^'"`]+)\1/) do |match|
             quote_type, key = match
-
-            # If it's a backtick, ensure it's not a template literal with interpolation
-
             next if quote_type == "`" && key.include?("${")
 
-            keys << key
+            line = content[0..Regexp.last_match.begin(0)].count("\n") + 1
+            keys << {key: key, line: line}
           end
         end
 
-        # Extract keys from object properties (e.g., titleKey: "some.key")
+        # Extract keys from object properties
         config.key_properties.each do |prop|
-          # Matches: titleKey: "some.key" or titleKey: 'some.key'
           content.scan(/#{Regexp.escape(prop)}\s*:\s*(['"])([^'"]+)\1/) do |_quote, key|
-            keys << key if looks_like_i18n_key?(key)
+            if looks_like_i18n_key?(key)
+              line = content[0..Regexp.last_match.begin(0)].count("\n") + 1
+              keys << {key: key, line: line}
+            end
           end
         end
 

data/lib/inertia_i18n/parsers/vue_parser.rb

@@ -31,9 +31,9 @@ module InertiaI18n
         keys = []
 
         # v-t directive: v-t="'key'" or v-t='"key"'
-
         content.scan(/v-t\s*=\s*(["'])['"]([^'"]+)['"]\1/) do |match|
-          keys << match[1]
+          line = content[0..Regexp.last_match.begin(0)].count("\n") + 1
+          keys << {key: match[1], line: line}
         end
 
         keys

data/lib/inertia_i18n/scan_results.rb

@@ -2,17 +2,30 @@
 
 module InertiaI18n
   class ScanResults
-    attr_reader :files, :static_keys, :dynamic_patterns
+    attr_reader :files, :static_keys, :dynamic_patterns, :occurrences
 
     def initialize
       @files = {}
       @static_keys = Set.new
       @dynamic_patterns = []
+      @occurrences = Hash.new { |h, k| h[k] = [] }
     end
 
     def add_file(file, keys)
       @files[file] = keys
-      keys[:static].each { |key| @static_keys.add(key) }
+
+      keys[:static].each do |usage|
+        # Handle both legacy string keys and new usage objects
+        if usage.is_a?(Hash)
+          key = usage[:key]
+          @static_keys.add(key)
+          @occurrences[key] << {file: file, line: usage[:line]}
+        else
+          @static_keys.add(usage)
+          @occurrences[usage] << {file: file, line: nil}
+        end
+      end
+
       @dynamic_patterns.concat(keys[:dynamic])
     end
 
@@ -24,7 +37,8 @@ module InertiaI18n
       {
         files: @files,
         static_keys: @static_keys.to_a,
-        dynamic_patterns: @dynamic_patterns
+        dynamic_patterns: @dynamic_patterns,
+        occurrences: @occurrences
       }
     end
   end

data/lib/inertia_i18n/scanner.rb

@@ -18,12 +18,6 @@ module InertiaI18n
       results
     end
 
-    private
-
-    def frontend_files
-      @config.scan_paths.flat_map { |pattern| Dir.glob(pattern) }
-    end
-
     def parser_for_file(file)
       ext = File.extname(file).downcase
 
@@ -40,5 +34,11 @@ module InertiaI18n
         Parsers::BaseParser.new
       end
     end
+
+    private
+
+    def frontend_files
+      @config.scan_paths.flat_map { |pattern| Dir.glob(pattern) }
+    end
   end
 end

data/lib/inertia_i18n/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module InertiaI18n
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

data/lib/inertia_i18n.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+require "yaml"
+require "json"
+require "i18n"
+
 require_relative "inertia_i18n/version"
 require_relative "inertia_i18n/configuration"
 require_relative "inertia_i18n/converter"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: inertia_i18n
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Alexey Poimtsev
@@ -161,6 +161,7 @@ files:
 - lib/inertia_i18n/converter.rb
 - lib/inertia_i18n/file_converter.rb
 - lib/inertia_i18n/health_checker.rb
+- lib/inertia_i18n/i18n_tasks/scanner.rb
 - lib/inertia_i18n/locale_loader.rb
 - lib/inertia_i18n/normalizer.rb
 - lib/inertia_i18n/parsers/base_parser.rb