i18n-context-generator 0.3.0

data/lib/i18n_context_generator/writers/helpers.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module I18nContextGenerator
+  module Writers
+    # Shared utilities for writer classes (description filtering, file discovery).
+    module Helpers
+      def skip_description?(description)
+        description.include?('No usage found') || description.include?('Processing failed')
+      end
+
+      def writable_result?(result)
+        return false unless result&.description
+        return false unless result.error.nil?
+        return false if result.description.strip.empty?
+
+        !skip_description?(result.description)
+      end
+
+      def result_matches_source_path?(result, source_path)
+        return true unless result.respond_to?(:source_file) && result.source_file
+
+        File.expand_path(result.source_file) == File.expand_path(source_path)
+      end
+
+      def find_swift_files(path, ignore_patterns: [])
+        files = if File.file?(path) && path.end_with?('.swift')
+                  [path]
+                elsif File.directory?(path)
+                  Dir.glob(File.join(path, '**', '*.swift'))
+                else
+                  []
+                end
+
+        filter_ignored_paths(files, ignore_patterns)
+      end
+
+      private
+
+      def filter_ignored_paths(paths, ignore_patterns)
+        compiled_patterns = ignore_patterns.map { |pattern| glob_to_regex(pattern) }
+        paths.reject { |path| ignored_path?(path, compiled_patterns) }.sort
+      end
+
+      def ignored_path?(path, compiled_patterns)
+        compiled_patterns.any? { |pattern| pattern.match?(path) }
+      end
+
+      def glob_to_regex(glob_pattern)
+        regex_str = Regexp.escape(glob_pattern)
+                          .gsub('\*\*/', '(.*/)?')
+                          .gsub('\*\*', '.*')
+                          .gsub('\*', '[^/]*')
+                          .gsub('\?', '.')
+        Regexp.new("(?:^|/)#{regex_str}(?:$|/)")
+      end
+    end
+  end
+end

data/lib/i18n_context_generator/writers/json_writer.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module I18nContextGenerator
+  module Writers
+    # Writes extraction results to a JSON file.
+    class JsonWriter
+      def write(results, path)
+        output = {
+          generated_at: Time.now.iso8601,
+          version: I18nContextGenerator::VERSION,
+          total: results.size,
+          entries: results.sort_by(&:key).map do |result|
+            {
+              key: result.key,
+              text: result.text,
+              context: {
+                description: result.description,
+                ui_element: result.ui_element,
+                tone: result.tone,
+                max_length: result.max_length
+              },
+              locations: result.locations,
+              error: result.error
+            }
+          end
+        }
+
+        File.write(path, Oj.dump(output, indent: 2, mode: :compat))
+      end
+    end
+  end
+end

data/lib/i18n_context_generator/writers/strings_writer.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module I18nContextGenerator
+  module Writers
+    # Writer that updates iOS .strings files with context comments
+    # Uses the dotstrings gem for proper parsing and generation
+    class StringsWriter
+      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)
+
+        # Parse the existing file
+        original_file = DotStrings.parse_file(source_path, strict: false)
+        results_by_key = results.each_with_object({}) do |result, lookup|
+          next unless result_matches_source_path?(result, source_path)
+
+          lookup[result.key] = result
+        end
+
+        # Build new file with updated comments (DotStrings::Item is immutable)
+        new_file = DotStrings::File.new
+
+        original_file.items.each do |item|
+          result = results_by_key[item.key]
+
+          new_comment = if writable_result?(result)
+                          build_comment(item.comment, result.description)
+                        else
+                          item.comment
+                        end
+
+          new_item = DotStrings::Item.new(
+            key: item.key,
+            value: item.value,
+            comment: new_comment
+          )
+          new_file << new_item
+        end
+
+        # Write back to file
+        File.write(source_path, new_file.to_s)
+      end
+
+      private
+
+      def build_comment(existing_comment, context_description)
+        context_line = "#{@context_prefix}#{context_description}"
+
+        if existing_comment.nil? || existing_comment.empty? || @context_mode == 'replace'
+          context_line
+        elsif !@context_prefix.empty? && existing_comment.include?(@context_prefix)
+          # Replace existing context line (idempotent update)
+          existing_comment.gsub(/#{Regexp.escape(@context_prefix)}[^\n]*/, context_line)
+        else
+          # Append context to existing comment
+          "#{existing_comment}\n#{context_line}"
+        end
+      end
+    end
+  end
+end

data/lib/i18n_context_generator/writers/swift_writer.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module I18nContextGenerator
+  module Writers
+    # Writer that updates comment: parameters in Swift localization calls
+    # Supports NSLocalizedString, String(localized:), Text(), and custom functions
+    class SwiftWriter
+      include Helpers
+
+      SWIFT_STRING_PATTERN = '"(?:\\\\.|[^"\\\\])*"'
+      COMMENT_ARGUMENT_PATTERN = /comment:\s*"((?:\\.|[^"\\])*)"/
+      private_constant :SWIFT_STRING_PATTERN, :COMMENT_ARGUMENT_PATTERN
+
+      # Default patterns for Swift localization functions
+      # Each pattern should capture: (prefix)(key)(middle)(comment_value)(suffix)
+      DEFAULT_FUNCTIONS = %w[
+        NSLocalizedString
+        String(localized:
+        Text(
+      ].freeze
+
+      def initialize(functions: nil, context_prefix: 'Context: ', context_mode: 'replace')
+        @functions = functions || DEFAULT_FUNCTIONS
+        @context_prefix = context_prefix
+        @context_mode = context_mode
+      end
+
+      # Write context back to all Swift files that contain the keys
+      # @param results [Array] extraction results with key and description
+      # @param source_paths [Array<String>] paths to search for Swift files
+      def write_to_source_files(results, source_paths, ignore_patterns: [])
+        results_by_key = results.to_h { |r| [r.key, r] }
+
+        source_paths.each do |source_path|
+          swift_files = find_swift_files(source_path, ignore_patterns: ignore_patterns)
+
+          swift_files.each do |swift_file|
+            update_file(swift_file, results_by_key)
+          end
+        end
+      end
+
+      # Update a single Swift file with context comments
+      # @param path [String] path to Swift file
+      # @param results_by_key [Hash] results keyed by translation key
+      def update_file(path, results_by_key)
+        return unless File.exist?(path)
+
+        content = File.read(path)
+        original_content = content.dup
+        updated = false
+
+        results_by_key.each do |key, result|
+          next unless writable_result?(result)
+
+          new_content = update_comment_for_key(content, key, result.description)
+          if new_content != content
+            content = new_content
+            updated = true
+          end
+        end
+
+        if updated && content != original_content
+          File.write(path, content)
+          true
+        else
+          false
+        end
+      end
+
+      private
+
+      # Update comment for a specific key in the content
+      def update_comment_for_key(content, key, description)
+        escaped_key = Regexp.escape(key)
+
+        @functions.each do |func|
+          # Build pattern based on function type
+          pattern = build_pattern_for_function(func, escaped_key)
+          next unless pattern
+
+          # Try to match and replace
+          content = content.gsub(pattern) do |match|
+            update_match(match, func, key, description)
+          end
+        end
+
+        content
+      end
+
+      def build_pattern_for_function(func, escaped_key)
+        comment_pattern = "comment:\\s*#{SWIFT_STRING_PATTERN}"
+
+        case func
+        when 'NSLocalizedString'
+          # NSLocalizedString("key", comment: "...")
+          # NSLocalizedString("key", value: "...", comment: "...")
+          # NSLocalizedString("key", tableName: "...", comment: "...")
+          Regexp.new("NSLocalizedString\\(\\s*\"#{escaped_key}\"[^)]*#{comment_pattern}[^)]*\\)", Regexp::MULTILINE)
+        when 'String(localized:'
+          # String(localized: "key", comment: "...")
+          Regexp.new("String\\(\\s*localized:\\s*\"#{escaped_key}\"[^)]*#{comment_pattern}[^)]*\\)", Regexp::MULTILINE)
+        when 'Text('
+          # Text("key", comment: "...")
+          # Text(LocalizedStringKey("key"), comment: "...")
+          Regexp.new("Text\\([^)]*\"#{escaped_key}\"[^)]*#{comment_pattern}[^)]*\\)", Regexp::MULTILINE)
+        else
+          # Custom function - assume pattern like: func("key", ..., comment: "...")
+          escaped_func = Regexp.escape(func)
+          Regexp.new("#{escaped_func}\\([^)]*\"#{escaped_key}\"[^)]*#{comment_pattern}[^)]*\\)", Regexp::MULTILINE)
+        end
+      end
+
+      def update_match(match, _func, _key, new_comment)
+        # Replace the comment value while preserving the rest of the call
+        match.gsub(COMMENT_ARGUMENT_PATTERN) do |_comment_match|
+          existing_comment = unescape_swift_string(Regexp.last_match(1))
+          final_comment = build_final_comment(existing_comment, new_comment)
+          "comment: \"#{escape_swift_string(final_comment)}\""
+        end
+      end
+
+      def build_final_comment(existing_comment, new_context)
+        context_line = "#{@context_prefix}#{new_context}"
+
+        if existing_comment.nil? || existing_comment.empty? || @context_mode == 'replace'
+          context_line
+        elsif !@context_prefix.empty? && existing_comment.include?(@context_prefix)
+          # Update existing context line (idempotent)
+          existing_comment.gsub(/#{Regexp.escape(@context_prefix)}[^\n]*/, context_line)
+        else
+          # Append context to existing comment
+          "#{existing_comment} #{context_line}"
+        end
+      end
+
+      def escape_swift_string(str)
+        str.gsub('\\', '\\\\')
+           .gsub('"', '\\"')
+           .gsub("\r", '\\r')
+           .gsub("\n", '\\n')
+           .gsub("\t", '\\t')
+      end
+
+      def unescape_swift_string(str)
+        escape_map = {
+          '"' => '"',
+          '\\' => '\\',
+          'n' => "\n",
+          'r' => "\r",
+          't' => "\t"
+        }
+
+        str.gsub(/\\(["\\nrt])/) do
+          escape_map.fetch(Regexp.last_match(1))
+        end
+      end
+    end
+  end
+end

data/lib/i18n_context_generator.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'csv'
+require 'digest'
+require 'fileutils'
+require 'oj'
+require 'concurrent'
+require 'tty-progressbar'
+require 'dotstrings'
+
+require_relative 'i18n_context_generator/version'
+require_relative 'i18n_context_generator/config'
+require_relative 'i18n_context_generator/parsers/base'
+require_relative 'i18n_context_generator/parsers/json_parser'
+require_relative 'i18n_context_generator/parsers/yaml_parser'
+require_relative 'i18n_context_generator/parsers/strings_parser'
+require_relative 'i18n_context_generator/parsers/android_xml_parser'
+require_relative 'i18n_context_generator/searcher'
+require_relative 'i18n_context_generator/llm/client'
+require_relative 'i18n_context_generator/llm/anthropic'
+require_relative 'i18n_context_generator/llm/openai'
+require_relative 'i18n_context_generator/writers/helpers'
+require_relative 'i18n_context_generator/writers/csv_writer'
+require_relative 'i18n_context_generator/writers/json_writer'
+require_relative 'i18n_context_generator/writers/strings_writer'
+require_relative 'i18n_context_generator/writers/android_xml_writer'
+require_relative 'i18n_context_generator/writers/swift_writer'
+require_relative 'i18n_context_generator/cache'
+require_relative 'i18n_context_generator/git_diff'
+require_relative 'i18n_context_generator/platform_validator'
+require_relative 'i18n_context_generator/context_extractor'
+
+module I18nContextGenerator
+  class Error < StandardError; end
+end

metadata

@@ -0,0 +1,196 @@
+--- !ruby/object:Gem::Specification
+name: i18n-context-generator
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- Automattic
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-03-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: dotstrings
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: oj
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.16'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.16'
+- !ruby/object:Gem::Dependency
+  name: rexml
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: tty-progressbar
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.18'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.18'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A CLI tool that analyzes source code to extract contextual information
+  for translation keys, improving translation quality with AI-powered analysis.
+email: mobile@automattic.com
+executables:
+- i18n-context-generator
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- exe/i18n-context-generator
+- lib/i18n_context_generator.rb
+- lib/i18n_context_generator/cache.rb
+- lib/i18n_context_generator/cli.rb
+- lib/i18n_context_generator/config.rb
+- lib/i18n_context_generator/context_extractor.rb
+- lib/i18n_context_generator/git_diff.rb
+- lib/i18n_context_generator/llm/anthropic.rb
+- lib/i18n_context_generator/llm/client.rb
+- lib/i18n_context_generator/llm/openai.rb
+- lib/i18n_context_generator/parsers/android_xml_parser.rb
+- lib/i18n_context_generator/parsers/base.rb
+- lib/i18n_context_generator/parsers/json_parser.rb
+- lib/i18n_context_generator/parsers/strings_parser.rb
+- lib/i18n_context_generator/parsers/yaml_parser.rb
+- lib/i18n_context_generator/platform_validator.rb
+- lib/i18n_context_generator/searcher.rb
+- lib/i18n_context_generator/version.rb
+- lib/i18n_context_generator/writers/android_xml_writer.rb
+- lib/i18n_context_generator/writers/csv_writer.rb
+- lib/i18n_context_generator/writers/helpers.rb
+- lib/i18n_context_generator/writers/json_writer.rb
+- lib/i18n_context_generator/writers/strings_writer.rb
+- lib/i18n_context_generator/writers/swift_writer.rb
+homepage: https://github.com/Automattic/i18n-context-generator
+licenses:
+- MPL-2.0
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: Extract translation context from source code using AI
+test_files: []