i18n-context-generator 0.3.0

data/lib/i18n_context_generator/platform_validator.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require 'find'
+
+module I18nContextGenerator
+  # Validates that a run targets a single mobile platform after applying ignore rules.
+  class PlatformValidator
+    def initialize(config)
+      @config = config
+      @ignore_patterns = @config.ignore_patterns.map { |pattern| glob_to_regex(pattern) }
+    end
+
+    def validate!
+      platforms = (@config.translations.flat_map { |path| translation_platforms_for_path(path) } +
+        @config.source_paths.flat_map { |path| source_platforms_for_path(path) }).uniq
+
+      return if platforms.size <= 1
+
+      raise Error, 'Mixed iOS and Android runs are not supported. Split them into separate invocations or config files.'
+    end
+
+    private
+
+    def translation_platforms_for_path(path)
+      basename = File.basename(path).downcase
+      ext = File.extname(path).downcase
+
+      case ext
+      when '.strings'
+        [:ios]
+      when '.xml'
+        basename == 'strings.xml' || path.include?('/res/values') ? [:android] : []
+      else
+        []
+      end
+    end
+
+    def source_platforms_for_path(path)
+      return [] unless File.exist?(path)
+
+      if File.file?(path)
+        platform = source_platform_for_file(path)
+        return platform ? [platform] : []
+      end
+
+      platforms = []
+
+      Find.find(path) do |file|
+        next unless File.file?(file)
+        next if ignored_source_file?(file)
+
+        platform = source_platform_for_file(file)
+        next unless platform
+        next if platforms.include?(platform)
+
+        platforms << platform
+        break if platforms.size == 2
+      end
+
+      platforms
+    end
+
+    def source_platform_for_file(path)
+      case File.extname(path).downcase
+      when '.swift', '.m', '.mm', '.h'
+        :ios
+      when '.kt', '.java'
+        :android
+      end
+    end
+
+    def ignored_source_file?(path)
+      @ignore_patterns.any? do |pattern|
+        candidates = [path]
+        @config.source_paths.each do |root|
+          prefix = root.end_with?('/') ? root : "#{root}/"
+          candidates << path.delete_prefix(prefix) if path.start_with?(prefix)
+        end
+        candidates.any? { |candidate| pattern.match?(candidate) }
+      end
+    end
+
+    def glob_to_regex(glob_pattern)
+      regex_str = Regexp.escape(glob_pattern)
+                        .gsub('\*\*/', '(.*/)?')
+                        .gsub('\*\*', '.*')
+                        .gsub('\*', '[^/]*')
+                        .gsub('\?', '.')
+      Regexp.new("(?:^|/)#{regex_str}(?:$|/)")
+    end
+  end
+end

data/lib/i18n_context_generator/searcher.rb

@@ -0,0 +1,447 @@
+# frozen_string_literal: true
+
+require 'find'
+
+module I18nContextGenerator
+  # Finds where translation keys are used in iOS and Android source code.
+  class Searcher
+    # Represents a code match with surrounding context
+    Match = Data.define(:file, :line, :match_line, :context, :enclosing_scope) do
+      def initialize(file:, line:, match_line: '', context: '', enclosing_scope: nil)
+        super
+      end
+    end
+
+    # Patterns that indicate false positive matches (not actual localization usage)
+    FALSE_POSITIVE_PATTERNS = [
+      /==\s*["']/,             # String comparisons like == "yes"
+      /["']\s*==/,             # String comparisons like "yes" ==
+      /!=\s*["']/,             # String comparisons like != "no"
+      /["']\s*!=/,             # String comparisons like "no" !=
+      /\.equals\(["']/,        # Java .equals("string")
+      /contentEquals\(["']/    # Kotlin contentEquals
+    ].freeze
+
+    # File extensions to search by platform
+    FILE_EXTENSIONS = {
+      ios: %w[.swift .m .mm .h].freeze,
+      android: %w[.kt .java .xml].freeze,
+      unknown: %w[.swift .m .mm .h .kt .java .xml].freeze
+    }.freeze
+
+    IOS_WRAPPER_DEFINITION_PATTERN =
+      /\b(static\s+)?(?:let|var)\s+(\w+)\s*=\s*(?:NSLocalizedString|String\s*\(\s*localized:|LocalizedStringKey\s*\(|Text\s*\()/
+    IOS_TYPE_DECLARATION_PATTERN = /\b(class|struct|enum|extension)\s+(\w+)/
+
+    def initialize(source_paths:, ignore_patterns:, context_lines: 15, platform: nil)
+      @source_paths = source_paths
+      @ignore_patterns = compile_ignore_patterns(ignore_patterns)
+      @context_lines = context_lines
+      @platform = platform || detect_platform
+
+      # Cache discovered files for repeated searches
+      @files_cache = nil
+      @file_lines_cache = {}
+    end
+
+    def search(key)
+      patterns = build_search_patterns(key)
+      files = discover_files
+      direct_matches = []
+
+      files.each do |file|
+        matches = search_file(file, patterns, key)
+        direct_matches.concat(matches)
+      end
+
+      all_matches = if @platform == :ios
+                      search_ios_wrapper_usages(direct_matches, files) + direct_matches
+                    else
+                      direct_matches
+                    end
+
+      filter_matches(all_matches, key)
+    end
+
+    private
+
+    def detect_platform
+      @source_paths.each do |path|
+        next unless File.exist?(path)
+
+        if File.directory?(path)
+          Find.find(path) do |f|
+            if File.directory?(f) && ignored?(f)
+              Find.prune
+              next
+            end
+
+            next unless File.file?(f)
+            next if ignored?(f)
+
+            return :ios if f.end_with?('.swift', '.m', '.mm', '.h')
+            return :android if f.end_with?('.kt', '.java')
+          end
+        elsif !ignored?(path) && path.end_with?('.swift', '.m', '.mm', '.h')
+          return :ios
+        elsif !ignored?(path) && path.end_with?('.kt', '.java')
+          return :android
+        end
+      end
+      :unknown
+    end
+
+    def compile_ignore_patterns(patterns)
+      patterns.map { |p| glob_to_regex(p) }
+    end
+
+    def glob_to_regex(glob_pattern)
+      # Convert glob pattern to regex
+      # Handle common glob patterns: *, **, ?
+      regex_str = Regexp.escape(glob_pattern)
+                        .gsub('\*\*/', '(.*/)?')  # **/ matches any path (including empty)
+                        .gsub('\*\*', '.*')       # ** matches anything
+                        .gsub('\*', '[^/]*')      # * matches within path segment
+                        .gsub('\?', '.')          # ? matches single char
+      Regexp.new("(?:^|/)#{regex_str}(?:$|/)")
+    end
+
+    def discover_files
+      return @files_cache if @files_cache
+
+      extensions = FILE_EXTENSIONS[@platform] || FILE_EXTENSIONS[:unknown]
+      files = []
+
+      @source_paths.each do |path|
+        if File.file?(path)
+          files << path if extensions.any? { |ext| path.end_with?(ext) }
+        elsif File.directory?(path)
+          # Build a single glob pattern for all extensions
+          ext_pattern = extensions.size == 1 ? "*#{extensions.first}" : "*{#{extensions.join(',')}}"
+          files.concat(Dir.glob(File.join(path, '**', ext_pattern)))
+        end
+      end
+
+      # Apply ignore patterns and cache
+      @files_cache = files.reject { |f| ignored?(f) }
+    end
+
+    def ignored?(file)
+      @ignore_patterns.any? { |pattern| pattern.match?(file) }
+    end
+
+    def search_file(file, patterns, key, enable_multiline: true)
+      matches = []
+      lines = []
+      match_indices = Set.new
+
+      # Read file and find all matching line indices in a single pass
+      File.foreach(file).with_index do |line, index|
+        line = line.chomp
+        lines << line
+
+        # Check if any pattern matches this line
+        match_indices << index if patterns.any? { |pattern| pattern.match?(line) }
+      end
+
+      # For iOS files, also check for multi-line NSLocalizedString patterns
+      # where the function call and key are on different lines
+      if enable_multiline && @platform == :ios && file.end_with?('.swift', '.m', '.mm', '.h')
+        multiline_matches = find_multiline_ios_matches(lines, patterns, key)
+        match_indices.merge(multiline_matches)
+      end
+
+      # Build Match objects for each match with context
+      match_indices.each do |match_index|
+        context = extract_context(lines, match_index)
+        scope = extract_enclosing_scope(lines, match_index)
+        matches << Match.new(
+          file: file,
+          line: match_index + 1, # 1-indexed line numbers
+          match_line: lines[match_index],
+          context: context,
+          enclosing_scope: scope
+        )
+      end
+
+      matches
+    rescue Errno::ENOENT, Errno::EACCES, Errno::EISDIR => e
+      # Skip files that can't be read
+      warn "Warning: Could not read #{file}: #{e.message}" if $VERBOSE
+      []
+    rescue ArgumentError => e
+      # Skip files with encoding issues (binary files, etc.)
+      return [] if e.message.include?('invalid byte sequence')
+
+      raise
+    end
+
+    def search_ios_wrapper_usages(direct_matches, files)
+      references = direct_matches.filter_map do |match|
+        ios_wrapper_reference(match)
+      end.uniq
+
+      references.flat_map do |reference|
+        matches = []
+        local_pattern = ios_wrapper_local_pattern(reference)
+        qualified_pattern = ios_wrapper_qualified_pattern(reference)
+
+        matches.concat(
+          search_file(reference[:definition_file], [local_pattern], reference[:member_name], enable_multiline: false)
+        )
+
+        cross_file_pattern = qualified_pattern || local_pattern
+        cross_file_candidates = if qualified_pattern || reference[:type_path].size == 1
+                                  files.reject { |file| file == reference[:definition_file] }
+                                else
+                                  []
+                                end
+
+        cross_file_candidates.each do |file|
+          matches.concat(search_file(file, [cross_file_pattern], reference[:member_name], enable_multiline: false))
+        end
+
+        matches.reject do |match|
+          match.file == reference[:definition_file] && match.line == reference[:definition_line]
+        end
+      end
+    end
+
+    def ios_wrapper_reference(match)
+      return unless File.extname(match.file).downcase == '.swift'
+
+      lines = cached_file_lines(match.file)
+      definition_index = find_ios_wrapper_definition_index(lines, match.line - 1)
+      return unless definition_index
+
+      definition_line = lines[definition_index]
+      definition_match = IOS_WRAPPER_DEFINITION_PATTERN.match(definition_line)
+      return unless definition_match&.captures&.first
+
+      type_path = find_ios_type_path(lines, definition_index)
+      return if type_path.empty?
+
+      {
+        type_path: type_path,
+        member_name: definition_match[2],
+        definition_file: match.file,
+        definition_line: definition_index + 1
+      }
+    end
+
+    def cached_file_lines(file)
+      @file_lines_cache[file] ||= File.readlines(file, chomp: true)
+    end
+
+    def find_ios_wrapper_definition_index(lines, match_index, lookback: 5)
+      start_idx = [0, match_index - lookback].max
+
+      match_index.downto(start_idx) do |index|
+        return index if IOS_WRAPPER_DEFINITION_PATTERN.match?(lines[index])
+      end
+
+      nil
+    end
+
+    def find_ios_type_path(lines, index)
+      scope_stack = []
+      brace_depth = 0
+      pending_type = nil
+
+      lines[0..index].each do |line|
+        if (type_match = IOS_TYPE_DECLARATION_PATTERN.match(line))
+          if line.include?('{')
+            scope_stack << { name: type_match[2], depth: brace_depth + 1 }
+          else
+            pending_type = { name: type_match[2], depth: brace_depth + 1 }
+          end
+        elsif pending_type && line.include?('{')
+          scope_stack << pending_type
+          pending_type = nil
+        end
+
+        brace_depth += line.count('{') - line.count('}')
+        scope_stack.pop while scope_stack.any? && scope_stack.last[:depth] > brace_depth
+      end
+
+      scope_stack.map { |scope| scope[:name] }
+    end
+
+    def ios_wrapper_local_pattern(reference)
+      local_type_name = reference[:type_path].last
+      Regexp.new("\\b#{Regexp.escape(local_type_name)}\\.#{Regexp.escape(reference[:member_name])}\\b")
+    end
+
+    def ios_wrapper_qualified_pattern(reference)
+      return nil unless reference[:type_path].size > 1
+
+      qualified_type_path = reference[:type_path].join('.')
+      Regexp.new("\\b#{Regexp.escape(qualified_type_path)}\\.#{Regexp.escape(reference[:member_name])}\\b")
+    end
+
+    # Find matches where localization calls span multiple lines
+    # e.g., NSLocalizedString(\n    "key",\n    comment: "...")
+    def find_multiline_ios_matches(lines, patterns, key)
+      key_pattern = /["']#{Regexp.escape(key)}["']/
+
+      lines.each_with_index.filter_map do |line, index|
+        next if patterns.any? { |p| p.match?(line) }  # Already a single-line match
+        next unless key_pattern.match?(line)          # Doesn't contain the key
+
+        index if preceded_by_localization_opener?(lines, index)
+      end.to_set
+    end
+
+    def preceded_by_localization_opener?(lines, index, lookback: 5)
+      start_idx = [0, index - lookback].max
+
+      (start_idx...index).reverse_each do |i|
+        line = lines[i]
+        return true if IOS_FUNCTION_OPENERS.any? { |opener| opener.match?(line) }
+        return false if line =~ /;\s*$/ || line =~ /\)\s*$/ # Hit a statement boundary
+      end
+
+      false
+    end
+
+    # Scan backwards from the match to find the nearest enclosing function/class/struct
+    def extract_enclosing_scope(lines, match_index)
+      match_index.downto(0) do |i|
+        line = lines[i]
+        return "#{::Regexp.last_match(1)} #{::Regexp.last_match(2)}" if line =~ /\b(func|class|struct|enum|protocol)\s+(\w+)/
+        # Android/Kotlin patterns
+        return "#{::Regexp.last_match(1)} #{::Regexp.last_match(2)}" if line =~ /\b(fun|class|object)\s+(\w+)/
+      end
+      nil
+    end
+
+    def extract_context(lines, match_index)
+      start_idx = [0, match_index - @context_lines].max
+      end_idx = [lines.length - 1, match_index + @context_lines].min
+
+      context_parts = (start_idx..end_idx).map do |i|
+        i == match_index ? ">>> #{lines[i]}" : lines[i]
+      end
+
+      context_parts.join("\n")
+    end
+
+    def build_search_patterns(key)
+      pattern_strings = case @platform
+                        when :ios
+                          build_ios_patterns(key)
+                        when :android
+                          build_android_patterns(key)
+                        else
+                          build_ios_patterns(key) + build_android_patterns(key) + [Regexp.escape(key)]
+                        end
+
+      # Pre-compile all patterns for this search
+      pattern_strings.map { |p| Regexp.new(p) }
+    end
+
+    # Extract the base resource name from composite Android keys
+    # e.g., "post_likes_count:one" -> "post_likes_count"
+    #        "days_of_week[0]"     -> "days_of_week"
+    def android_base_key(key)
+      key.sub(/:[a-z]+$/, '').sub(/\[\d+\]$/, '')
+    end
+
+    # Patterns that indicate the start of a localization function call
+    # Used for multi-line matching when the key is on a different line
+    IOS_FUNCTION_OPENERS = [
+      /NSLocalizedString\s*\(\s*$/,
+      /String\s*\(\s*localized:\s*$/,
+      /LocalizedStringKey\s*\(\s*$/,
+      /Text\s*\(\s*$/
+    ].freeze
+    private_constant :IOS_FUNCTION_OPENERS
+
+    def build_ios_patterns(key)
+      escaped = Regexp.escape(key)
+      [
+        # NSLocalizedString("key", ...) - most common (Swift and Obj-C)
+        # Note: @? handles optional @ prefix for Objective-C @"string" syntax
+        "NSLocalizedString\\s*\\(\\s*@?[\"']#{escaped}[\"']",
+        # String(localized: "key", ...) - modern Swift
+        "String\\s*\\(\\s*localized:\\s*[\"']#{escaped}[\"']",
+        # LocalizedStringKey("key") - SwiftUI
+        "LocalizedStringKey\\s*\\(\\s*[\"']#{escaped}[\"']",
+        # Text("key") - SwiftUI (when using localized strings)
+        "Text\\s*\\(\\s*[\"']#{escaped}[\"']",
+        # .localized extension pattern
+        "[\"']#{escaped}[\"']\\.localized"
+      ]
+    end
+
+    def build_android_patterns(key)
+      base = android_base_key(key)
+      escaped_base = Regexp.escape(base)
+
+      if key =~ /:[a-z]+$/
+        # Plural key (e.g., "post_likes_count:one") — search by base name in plural resources
+        [
+          "R\\.plurals\\.#{escaped_base}\\b",
+          "@plurals/#{escaped_base}\\b",
+          "getQuantityString\\s*\\(\\s*R\\.plurals\\.#{escaped_base}",
+          "\\.getQuantityString\\s*\\(\\s*R\\.plurals\\.#{escaped_base}",
+          "pluralStringResource\\s*\\(\\s*R\\.plurals\\.#{escaped_base}",
+          "[\\(\\s,=]plurals\\.#{escaped_base}\\b"
+        ]
+      elsif key =~ /\[\d+\]$/
+        # Array key (e.g., "days_of_week[0]") — search by base name in array resources
+        [
+          "R\\.array\\.#{escaped_base}\\b",
+          "@array/#{escaped_base}\\b",
+          "getStringArray\\s*\\(\\s*R\\.array\\.#{escaped_base}",
+          "\\.getStringArray\\s*\\(\\s*R\\.array\\.#{escaped_base}",
+          "resources\\.getStringArray\\s*\\(\\s*R\\.array\\.#{escaped_base}",
+          "[\\(\\s,=]array\\.#{escaped_base}\\b"
+        ]
+      else
+        # Standard string key
+        escaped = Regexp.escape(key)
+        [
+          "R\\.string\\.#{escaped}\\b",
+          "@string/#{escaped}\\b",
+          "getString\\s*\\(\\s*R\\.string\\.#{escaped}",
+          "\\.getString\\s*\\(\\s*R\\.string\\.#{escaped}",
+          "stringResource\\s*\\(\\s*R\\.string\\.#{escaped}",
+          "[\\(\\s,=]string\\.#{escaped}\\b",
+          "getString\\s*\\(\\s*string\\.#{escaped}",
+          "stringResource\\s*\\(\\s*string\\.#{escaped}"
+        ]
+      end
+    end
+
+    def filter_matches(matches, key)
+      seen = Set.new
+      matches.select do |match|
+        location = "#{match.file}:#{match.line}"
+        next false if seen.include?(location)
+        next false if false_positive?(match.match_line, key)
+        next false if translation_file?(match.file)
+
+        seen.add(location)
+      end
+    end
+
+    def false_positive?(line, _key)
+      return false if line.nil? || line.empty?
+
+      FALSE_POSITIVE_PATTERNS.any? { |pattern| pattern.match?(line) }
+    end
+
+    def translation_file?(file)
+      basename = File.basename(file).downcase
+      ext = File.extname(file).downcase
+
+      # Skip translation files - we want code usage, not definitions
+      return true if ext == '.strings'
+      return true if basename == 'strings.xml'
+      return true if file.include?('/res/values') && ext == '.xml'
+
+      false
+    end
+  end
+end

data/lib/i18n_context_generator/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module I18nContextGenerator
+  VERSION = '0.3.0'
+end

data/lib/i18n_context_generator/writers/android_xml_writer.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module I18nContextGenerator
+  module Writers
+    # Writer that updates Android strings.xml files with context comments
+    # Uses line-by-line approach to preserve original formatting
+    class AndroidXmlWriter
+      include Helpers
+
+      def initialize(context_prefix: 'Context: ', context_mode: 'replace')
+        @context_prefix = context_prefix
+        @context_mode = context_mode
+      end
+
+      def write(results, source_path)
+        return unless File.exist?(source_path)
+
+        lines = File.readlines(source_path, encoding: 'UTF-8')
+        results_by_key = build_results_lookup(results, source_path)
+
+        output_lines = []
+        i = 0
+
+        while i < lines.length
+          line = lines[i]
+
+          # Only write comments on <string> elements, not <plurals> or <string-array>.
+          # Plural/array parent comments would use a single child's description which
+          # is misleading for the resource as a whole.
+          # Match the opening <string name="..."> tag — works for both single-line and
+          # multi-line string elements.
+          if (match = line.match(/^(\s*)<string\s+name="([^"]+)"/))
+            indent = match[1]
+            key = match[2]
+            result = results_by_key[key]
+
+            insert_context_comment(output_lines, indent, result.description) if writable_result?(result)
+          end
+
+          output_lines << line
+          i += 1
+        end
+
+        File.write(source_path, output_lines.join)
+      end
+
+      private
+
+      # Build a lookup that maps base resource names to results.
+      # For plural keys like "post_likes_count:one", maps "post_likes_count" to a result.
+      # For array keys like "days_of_week[0]", maps "days_of_week" to a result.
+      # Standard string keys map directly.
+      # Results are sorted by key first so the lookup is deterministic regardless
+      # of concurrent execution order.
+      def build_results_lookup(results, source_path = nil)
+        lookup = {}
+        results.sort_by(&:key).each do |r|
+          next if source_path && !result_matches_source_path?(r, source_path)
+
+          base = r.key.sub(/:[a-z]+$/, '').sub(/\[\d+\]$/, '')
+          lookup[base] ||= r
+          lookup[r.key] ||= r
+        end
+        lookup
+      end
+
+      def insert_context_comment(output_lines, indent, description)
+        context_text = "#{@context_prefix}#{escape_comment(description)}"
+
+        if output_lines.any? && output_lines.last.match?(/^\s*<!--.*-->\s*$/)
+          existing_match = output_lines.last.match(/^\s*<!--\s*(.*?)\s*-->\s*$/)
+          existing_comment = existing_match ? existing_match[1] : ''
+
+          if managed_comment?(existing_comment)
+            # Update existing context comment
+            output_lines.pop
+            new_comment = build_comment(existing_comment, context_text)
+            output_lines << "#{indent}<!-- #{new_comment} -->\n"
+          else
+            # Preceding comment is not ours (e.g. a section header) — leave it, insert new
+            output_lines << "#{indent}<!-- #{context_text} -->\n"
+          end
+        else
+          output_lines << "#{indent}<!-- #{context_text} -->\n"
+        end
+      end
+
+      # A comment is managed by us if it contains the configured context prefix.
+      # When prefix is empty, we cannot distinguish managed from unmanaged comments,
+      # so we always treat the preceding comment as replaceable — the user accepted
+      # this trade-off by choosing an empty prefix.
+      def managed_comment?(comment)
+        @context_prefix.empty? || comment.include?(@context_prefix)
+      end
+
+      def build_comment(existing_comment, context_text)
+        if existing_comment.nil? || existing_comment.empty? || @context_mode == 'replace'
+          context_text
+        elsif !@context_prefix.empty? && existing_comment.include?(@context_prefix)
+          # Replace existing context line (idempotent update)
+          existing_comment.gsub(/#{Regexp.escape(@context_prefix)}[^\n]*/, context_text)
+        else
+          # Append context to existing comment
+          "#{existing_comment} #{context_text}"
+        end
+      end
+
+      def escape_comment(text)
+        # Remove any existing comment markers and newlines
+        text
+          .gsub('--', '- -') # Double dash not allowed in XML comments
+          .gsub("\n", ' ')
+          .strip
+      end
+    end
+  end
+end

data/lib/i18n_context_generator/writers/csv_writer.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module I18nContextGenerator
+  module Writers
+    # Writes extraction results to a CSV file.
+    class CsvWriter
+      HEADERS = %w[key text description ui_element tone max_length locations error].freeze
+      DANGEROUS_CSV_PREFIX = /\A[ \t\r\n]*[=+\-@]/
+
+      def write(results, path)
+        CSV.open(path, 'w') do |csv|
+          csv << HEADERS
+
+          results.sort_by(&:key).each do |result|
+            csv << [
+              sanitize_cell(result.key),
+              sanitize_cell(result.text),
+              sanitize_cell(result.description),
+              sanitize_cell(result.ui_element),
+              sanitize_cell(result.tone),
+              result.max_length,
+              sanitize_cell(result.locations.join(';')),
+              sanitize_cell(result.error)
+            ]
+          end
+        end
+      end
+
+      private
+
+      def sanitize_cell(value)
+        return value unless value.is_a?(String)
+        return value unless value.match?(DANGEROUS_CSV_PREFIX)
+
+        "'#{value}"
+      end
+    end
+  end
+end