i18n-context-generator 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e8761f1cd9b514b6d8de047f23dd3439770039e5c96d639468a3be93db28730
-  data.tar.gz: 739ded1c82976fcbd7756a8363a6e667a6bce6641c0544b0cee5482c16355b73
+  metadata.gz: 6588c09e273cb74c40dba8cc26798e46b82b5d47e5c840f6e4609843bb1f5ed8
+  data.tar.gz: 9b3e309fd4030a99e065a2c7693240f09d205f9d95323a9744ecb3eaa1b239b1
 SHA512:
-  metadata.gz: 0bc26c4fe73b9fc8e17d273ce6f471e23f5febde0419ed8eb8c02570a36c945a287e95c85af15ebf02d8a001ee95d46e950a7b4129e4f4f9bf5e483f205b3371
-  data.tar.gz: 934d026c57e651fa81ae2c436c49ea41bfcf8498c1ce888090c022a82837f31a21d6cb669c4d22a39ebc2e9cee4ac5ae5d578bf26b1978703ad1112a7030762e
+  metadata.gz: 2a7b9df974f135375341c7c1a5f73e40575f10c92d11a72ecc976ecef9ae6b25aac32351f1468c79671c870d87c2df576664a96b32ef00128815fc4ff016de1c
+  data.tar.gz: 0cc9db25973ffe209dea8cb4197df899310320361f0a8da2e45fa597fc592867bea22cdd5ad5337907c18cbdf824e269955fe79550baedd23f0d919fdef73c00

data/README.md

@@ -2,17 +2,18 @@
 
 `i18n-context-generator` generates translator-facing context for your existing localization keys. It reads translation files, finds where each key is used in app code, and asks an LLM to explain the string's UI role in plain language.
 
-You can export the results as CSV or JSON, write them back into `.strings` or `strings.xml`, or update Swift `comment:` arguments directly.
+You can export the results as CSV or JSON, write them back into `.strings`, `.xcstrings`, or `strings.xml`, or update Swift `comment:` arguments directly.
 
 It is designed for mobile codebases. Each run must target either iOS or Android, not both.
 
 ## What It Does
 
-- Parses `.strings`, `strings.xml`, `.json`, and `.yml` or `.yaml` translation files
+- Parses `.strings`, `.xcstrings`, `strings.xml`, `.json`, and `.yml` or `.yaml` translation files
 - Searches Swift, Objective-C, Kotlin, Java, and Android XML for matching usages
-- Uses Anthropic or OpenAI models to infer UI context
+- Uses Anthropic, OpenAI, or an explicitly configured OpenAI-compatible endpoint to infer UI context
 - Supports diff-based runs, key filters, and key ranges for incremental work
-- Redacts likely secrets, URLs, and emails from prompts by default
+- Separates validation, planning, patch preview, and mutation into explicit workflow stages
+- Applies best-effort redaction of likely secrets, URLs, and emails by default
 - Optionally caches results to avoid repeating identical LLM work
 
 ## Installation
@@ -24,13 +25,12 @@ chmod +x exe/i18n-context-generator
 
 ## Quick Start
 
-Preview what would be processed:
+Plan what would be processed without calling an LLM:
 
 ```bash
-bundle exec exe/i18n-context-generator extract \
+bundle exec exe/i18n-context-generator plan \
   -t ios/MyApp/Resources/Localizable.strings \
-  -s ios/MyApp \
-  --dry-run
+  -s ios/MyApp
 ```
 
 For a real run, set a provider API key:
@@ -77,7 +77,7 @@ bundle exec exe/i18n-context-generator extract \
   --write-back-to-code
 ```
 
-Use `--output`, `--write-back`, or `--write-back-to-code` depending on where you want results to go. If you have both iOS and Android code in the same repository, run the tool separately for each platform.
+Use `--output`, `--stdout`, `--write-back`, or `--write-back-to-code` depending on where you want results to go. `extract` uses the configured `workflow.stage`, which defaults to `apply`; the named workflow commands always select their corresponding stage explicitly. If you have both iOS and Android code in the same repository, run the tool separately for each platform.
 
 ## Configuration
 
@@ -91,35 +91,56 @@ bundle exec exe/i18n-context-generator extract --config .i18n-context-generator.
 Example `.i18n-context-generator.yml`:
 
 ```yaml
+schema_version: 1
+
 translations:
   - path: ios/MyApp/Resources/Localizable.strings
 
 source:
   paths:
     - ios/MyApp
+  # Optional additions to the built-in dependency, build, and test ignores
   ignore:
-    - "**/Pods/**"
-    - "**/build/**"
-    - "**/*Tests*"
+    - "**/*.generated.*"
+
+context:
+  # Free-form text or Markdown included in full for every selected key.
+  files:
+    - GLOSSARY.md
+    - docs/localization-style.md
 
 llm:
   provider: anthropic
-  model: claude-sonnet-4-6
+  # Optional; each provider has its own default model.
+  # model: claude-sonnet-4-6
+  # openai_compatible requires an explicit model and endpoint.
+  # endpoint: http://127.0.0.1:11434/v1/responses
 
 processing:
   concurrency: 5
   context_lines: 15
   max_matches_per_key: 3
+  max_prompt_chars: 50000
+
+cache:
+  enabled: false
+  directory: .i18n-context-generator-cache
+
+workflow:
+  stage: apply
 
 output:
   format: csv
   path: translation-context.csv
+  stdout: false
   write_back: false
   write_back_to_code: false
   context_prefix: "Context: "
   context_mode: replace
 
 swift:
+  # These syntaxes are used by extraction and Swift comment write-back.
+  # Custom entries extend the built-in defaults shown below.
   functions:
     - NSLocalizedString
     - "String(localized:"
@@ -128,48 +149,96 @@ swift:
 privacy:
   include_file_paths: false
   include_translation_comments: true
+  # Best-effort only; source snippets are still sent to the remote provider.
   redact_prompts: true
 ```
 
 Use a separate config for Android instead of mixing iOS and Android paths in the same run.
+Client `source.ignore` entries extend the built-in ignore list; they do not replace it.
+Configured `swift.functions` extend the built-in defaults and are used consistently for usage search, source-first discovery, and `--write-back-to-code`. A custom function may be written as either `MyLocalizedString` or `MyLocalizedString(`; its first string argument, with or without a label such as `key:`, is treated as the translation key.
+Unversioned configuration files use schema version 1 compatibility mode: unknown options produce warnings and remain ignored as they were before versioning. New files should declare `schema_version: 1`; explicit versioning enables strict unknown-option validation, and future versions fail clearly. Run `i18n-context-generator config validate [PATH]` to validate a file or add `--print-config` to an extraction command to inspect the fully resolved, secret-free configuration.
 
 ## CLI Reference
 
 ### Inputs and Output
 
-- `-t`, `--translations FILES`: translation files to process, comma-separated
-- `-s`, `--source DIRS`: source files or directories to search, comma-separated
+- `-t`, `--translation FILE`: translation file to process; repeat for multiple files
+- `-s`, `--source PATH`: source file or directory to search; repeat for multiple paths
+- `--context-file PATH`: free-form supplemental context file; repeat for multiple files
 - `-c`, `--config PATH`: load options from `.i18n-context-generator.yml`
 - `-o`, `--output PATH`: write results to a file
+- `--stdout`: write structured CSV or JSON to standard output
 - `-f`, `--format csv|json`: output format, default `csv`
+- `--print-config`: print the resolved configuration and exit
 
 ### LLM Settings
 
-- `-p`, `--provider anthropic|openai`: LLM provider, default `anthropic`
+- `-p`, `--provider anthropic|openai|openai_compatible`: LLM provider, default `anthropic`
 - `-m`, `--model MODEL`: explicit model override
+- `--endpoint URL`: explicit Responses API endpoint for `openai_compatible`
 - `--concurrency N`: parallel request count, default `5`
+- `--max-prompt-chars N`: hard character limit per LLM prompt, default `50000`
 
 ### Filtering and Incremental Runs
 
-- `-k`, `--keys PATTERNS`: wildcard key filter such as `settings.*`
+- `-k`, `--key PATTERN`: wildcard key filter such as `settings.*`; repeat for multiple patterns
 - `--diff-base REF`: process only keys changed since a Git ref
+- `--diff-head REF`: compare `--diff-base` to this ref, default `HEAD`
 - `--start-key KEY`: start at a specific key, inclusive
 - `--end-key KEY`: stop at a specific key, inclusive
 - `--dry-run`: preview matching keys without calling the LLM
 
 ### Write-Back and Prompt Controls
 
-- `--write-back`: update `.strings` or `strings.xml`
+- `--write-back`: update `.strings`, `.xcstrings`, or `strings.xml`
 - `--write-back-to-code`: update Swift `comment:` arguments
 - `--context-prefix TEXT`: prefix generated comments, default `Context: `
 - `--context-mode replace|append`: replace existing comments or append to them
 - `--cache`: enable on-disk caching
+- `--cache-dir PATH`: cache directory, default `.i18n-context-generator-cache`
 - `--include-file-paths`: include full source paths in prompts
 - `--include-translation-comments`: include existing translation comments in prompts, default `true`
-- `--redact-prompts`: redact likely secrets and PII before prompts are sent, default `true`
+- `--redact-prompts`: best-effort redact likely secrets and PII before prompts are sent, default `true`
 
 Run `bundle exec exe/i18n-context-generator help extract` for the full command reference.
 
+The legacy `--translations` and `--keys` flags still accept comma-separated lists with a deprecation warning. Repeatable singular flags always preserve literal commas in paths and key patterns.
+
+### Workflow stages
+
+- `check`: validate configuration and confirm source usage without calling the LLM
+- `plan`: list selected keys and destinations without calling the LLM
+- `preview-diff`: generate context and print the exact write-back patch to stdout
+  without changing translation, source, or structured-output files; diagnostics
+  go to stderr
+- `apply`: generate context and write to the configured destinations
+- `extract`: compatibility entry point that uses `workflow.stage` from configuration, defaulting to `apply`
+
+`--dry-run` remains available as a compatibility shortcut for non-mutating key selection. Use `preview-diff` when you need to inspect generated write-back content rather than only the selected keys.
+
+### Prompt privacy and size
+
+Remote-provider runs send translation text, selected source snippets, configured context files, and programmatic supplemental context off the machine. By default, full paths are reduced to basenames and the tool applies pattern-based redaction to keys, text, comments, paths, scopes, matched lines, surrounding context, and supplemental context. This is a best-effort safeguard, not a guarantee that all private or identifying data will be detected. Review every input you configure before using a remote provider.
+
+All context files are treated as opaque, untrusted evidence: they are neither parsed as a glossary nor filtered for relevance, and their complete contents are included in every selected key's request. Named runtime context follows the same contract. Evidence cannot override the system prompt or instruct the model, but prompt-injection defenses are not a substitute for reviewing sensitive inputs.
+
+`processing.max_prompt_chars` bounds each user prompt. When evidence exceeds the limit, surrounding code and optional metadata are truncated deterministically, with the translation key, text, and at least one usage receiving priority. Supplemental context is never partially included: if all of it cannot fit alongside the minimum application evidence, extraction fails with guidance to reduce the context or raise the limit. Provider output is validated against the application contract before it can reach an output writer.
+
+For a local or third-party Responses API, select `openai_compatible` and configure both `llm.model` and `llm.endpoint`. Plain HTTP is accepted only for loopback endpoints; remote endpoints must use HTTPS. Authentication is isolated to `OPENAI_COMPATIBLE_API_KEY`, so this provider never implicitly forwards `OPENAI_API_KEY` to a custom host.
+
+```yaml
+llm:
+  provider: openai_compatible
+  model: local-model-name
+  endpoint: http://127.0.0.1:11434/v1/responses
+```
+
+### Cache behavior
+
+Caching is opt-in and stores successful results only; provider, resolved model, custom endpoint, prompt controls, source context, source-discovery locations, and supplemental-context content digests are part of each cache identity. Raw context-file and runtime-context contents are not stored in the cache identity. Writes use private temporary files and atomic replacement so concurrent workers cannot leave partial JSON behind.
+
+The default directory is `.i18n-context-generator-cache`. Add that directory—or your custom `cache.directory`—to the client repository's `.gitignore`; cached LLM output should not be committed. The generated starter configuration keeps caching disabled by default.
+
 ## Supported Inputs
 
 ### Translation Files
@@ -177,15 +246,24 @@ Run `bundle exec exe/i18n-context-generator help extract` for the full command r
 | Format | Notes |
 |--------|-------|
 | `.strings` | Apple strings files |
+| `.xcstrings` | Apple string catalogs; reads the source language, comments, and plural variations |
 | `strings.xml` | Android string resources, including plurals and arrays |
-| `.json` | Nested keys are flattened |
-| `.yml`, `.yaml` | Nested keys are flattened |
+| `.json` | Read-only hydration source; nested keys are flattened |
+| `.yml`, `.yaml` | Read-only hydration source; nested keys are flattened and locale roots must be configured explicitly |
+
+For Rails-style YAML files with a locale root, name that root in the translation entry. Without `locale:`, the top-level key is retained as part of every translation key; locale-shaped application namespaces are never guessed or removed.
+
+```yaml
+translations:
+  - path: config/locales/en.yml
+    locale: en
+```
 
 ### Source Search
 
 | Platform | Files searched | Typical patterns |
 |----------|----------------|------------------|
-| iOS | `.swift`, `.m`, `.mm`, `.h` | `NSLocalizedString`, `String(localized:)`, `LocalizedStringKey`, `Text`, `.localized` |
+| iOS | `.swift`, `.m`, `.mm`, `.h` | `NSLocalizedString`, `String(localized:)`, `LocalizedStringResource`, `LocalizedStringKey`, `Text`, `.localized` |
 | Android | `.kt`, `.java`, `.xml` | `R.string.*`, `getString(...)`, `stringResource(...)`, `@string/...`, plurals, arrays |
 
 ## Output
@@ -193,12 +271,19 @@ Run `bundle exec exe/i18n-context-generator help extract` for the full command r
 CSV example:
 
 ```csv
-key,text,description,ui_element,tone,max_length,locations,error
-settings.title,Settings,Navigation bar title for the main settings screen,navigation,neutral,15,ios/SettingsViewController.swift:17,
-common.save,Save,Primary action button in forms and edit screens,button,neutral,10,ios/ProfileViewController.swift:31,
-error.network,Unable to connect,Error message shown when network requests fail,alert,apologetic,,ios/ProfileViewController.swift:94,
+key,text,description,ui_element,tone,max_length,confidence,ambiguity_reason,locations,status,cache_hit,request_count,input_tokens,output_tokens,retries,error
+settings.title,Settings,Navigation bar title for the main settings screen,navigation,neutral,15,high,,ios/SettingsViewController.swift:17,success,false,1,834,61,0,
 ```
 
+JSON and CSV output schema version 1 includes source-file and translation-key
+identity, complete and changed-only evidence locations, side-aware translation
+diff locations, confidence, ambiguity, token counts, retries, and request count.
+This keeps duplicate keys from different translation files distinguishable. The
+run summary reports aggregate requests, cache hits, tokens, retries, and an
+estimated list-price cost when the selected model has known pricing. Cost is
+informational and does not account for provider-specific discounts or billing
+adjustments.
+
 With `--write-back`, generated context is written back into translation files:
 
 **Before**
@@ -251,6 +336,58 @@ bundle exec exe/i18n-context-generator extract \
   --context-prefix ""
 ```
 
+`--diff-base` compares against `HEAD` by default. Pass `--diff-head` when a CI system prepares explicit refs:
+
+```bash
+bundle exec exe/i18n-context-generator extract \
+  -t ios/Resources/Localizable.strings \
+  -s ios \
+  --diff-base danger_base \
+  --diff-head danger_head \
+  --output translation-context.json
+```
+
+Programmatic callers can use the same range and may pass enum-style options as strings or symbols:
+
+```ruby
+config = I18nContextGenerator::Config.new(
+  translations: ['ios/Resources/Localizable.strings'],
+  source_paths: ['ios'],
+  context_files: ['GLOSSARY.md', 'docs/localization-style.md'],
+  supplemental_context: {
+    'Pull request title' => 'Clarify Reader renewal labels',
+    'Pull request description' => 'Updates subscription-expiry messaging.'
+  },
+  discovery_mode: :translations,
+  provider: :anthropic,
+  diff_base: 'danger_base',
+  diff_head: 'danger_head'
+)
+
+extractor = I18nContextGenerator::ContextExtractor.new(
+  config,
+  quiet: true,
+  progress: false
+)
+extractor.run
+
+extractor.results.each do |result|
+  result.status                         # :success, :no_usage, or :error
+  result.actionable?                    # Safe to present to a user
+  result.locations                      # Every source location used as extraction evidence
+  result.changed_locations              # Source evidence changed inside the configured range
+  result.changed_location_groups        # Changed source lines grouped by localization occurrence
+  result.translation_key                # Owning translation resource (including Android collections)
+  # ChangedLocation objects with file, line, side (:left/:right), and an
+  # optional right-side fallback_line for review suggestions.
+  result.changed_translation_locations
+end
+```
+
+An invalid ref or failed `git diff` raises `I18nContextGenerator::Error`; it is never reported as an unchanged range.
+Programmatic callers may also inject `log_output:`, `structured_output:`, and
+`patch_output:` streams instead of using the process-wide standard streams.
+
 Example GitHub Actions step:
 
 ```yaml

data/lib/i18n_context_generator/android_resource.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+module I18nContextGenerator
+  # Canonical Android string-resource identity and source-span indexing.
+  module AndroidResource
+    TAG_TYPES = {
+      'string' => :string,
+      'plurals' => :plural,
+      'string-array' => :array
+    }.freeze
+    TYPE_TAGS = TAG_TYPES.invert.freeze
+    RESOURCE_OPEN_PATTERN = /<(?<tag>string-array|plurals|string)\b(?<attributes>[^>]*?)>/m
+    ITEM_OPEN_PATTERN = /<item\b(?<attributes>[^>]*?)>/m
+
+    Span = Data.define(:key, :base_key, :resource_type, :start_line, :end_line, :parent_start_line, :parent_end_line) do
+      def line_span
+        start_line..end_line
+      end
+
+      def parent_line_span
+        parent_start_line..parent_end_line
+      end
+
+      def cover?(line_number)
+        line_span.cover?(line_number)
+      end
+    end
+
+    # Query object shared by parsers and diff/location consumers.
+    class Index
+      attr_reader :entry_spans, :resource_spans
+
+      def initialize(entry_spans:, resource_spans:)
+        @entry_spans = entry_spans.freeze
+        @resource_spans = resource_spans.freeze
+        @entries_by_key = @entry_spans.group_by(&:key)
+      end
+
+      def span_for(key)
+        @entries_by_key[key]&.first
+      end
+
+      def base_key_at(line_number)
+        @resource_spans.find { |span| span.cover?(line_number) }&.base_key
+      end
+
+      def member_at(line_number, parent:)
+        matches = @entry_spans.select do |span|
+          span.base_key == parent && span.resource_type != :string && span.cover?(line_number)
+        end
+        keys = matches.map(&:key).uniq
+        keys.one? ? keys.first : nil
+      end
+    end
+
+    module_function
+
+    def base_key(key)
+      key.to_s.sub(/:[a-z]+$/, '').sub(/\[\d+\]$/, '')
+    end
+
+    def type_for(key, explicit: nil)
+      return explicit.to_sym if explicit
+      return :plural if key.to_s.match?(/:[a-z]+$/)
+      return :array if key.to_s.match?(/\[\d+\]$/)
+
+      :string
+    end
+
+    def composite_key(name, type:, quantity: nil, index: nil)
+      case type.to_sym
+      when :plural then "#{name}:#{quantity}"
+      when :array then "#{name}[#{index}]"
+      else name
+      end
+    end
+
+    def type_for_tag(tag)
+      TAG_TYPES[tag]
+    end
+
+    def tag_for_type(type)
+      TYPE_TAGS[type.to_sym]
+    end
+
+    def index(content)
+      Scanner.new(content).index
+    end
+
+    # Internal scanner that runs after XML syntax validation. It preserves line
+    # positions while masking comments and records parent plus child spans.
+    class Scanner
+      def initialize(content)
+        @content = content
+        @visible_content = mask_comments(content)
+        @line_starts = [0]
+        content.to_enum(:scan, /\n/).each { @line_starts << Regexp.last_match.end(0) }
+      end
+
+      def index
+        entry_spans = []
+        resource_spans = []
+        offset = 0
+
+        while (match = RESOURCE_OPEN_PATTERN.match(@visible_content, offset))
+          resource_end, closing_start = element_end(match, match[:tag])
+          span = resource_span(match, resource_end)
+          if span
+            resource_spans << span
+            if span.resource_type == :string
+              entry_spans << span
+            else
+              entry_spans.concat(item_spans(match.end(0), closing_start, span))
+            end
+          end
+          offset = [resource_end, match.end(0)].max
+        end
+
+        Index.new(entry_spans: entry_spans, resource_spans: resource_spans)
+      end
+
+      private
+
+      def resource_span(match, resource_end)
+        name = attribute(match[:attributes], 'name')
+        type = AndroidResource.type_for_tag(match[:tag])
+        return unless name && type
+
+        start_line = line_for(match.begin(0))
+        end_line = line_for([resource_end - 1, match.begin(0)].max)
+        Span.new(
+          key: name,
+          base_key: name,
+          resource_type: type,
+          start_line: start_line,
+          end_line: end_line,
+          parent_start_line: start_line,
+          parent_end_line: end_line
+        )
+      end
+
+      def item_spans(content_start, content_end, parent_span)
+        spans = []
+        offset = content_start
+        array_index = 0
+
+        while offset < content_end && (match = ITEM_OPEN_PATTERN.match(@visible_content, offset))
+          break if match.begin(0) >= content_end
+
+          item_end, = element_end(match, 'item', limit: content_end)
+          key = item_key(match, parent_span, array_index)
+          spans << child_span(key, match.begin(0), item_end, parent_span) if key
+          array_index += 1 if parent_span.resource_type == :array
+          offset = [item_end, match.end(0)].max
+        end
+        spans
+      end
+
+      def item_key(match, parent_span, array_index)
+        quantity = attribute(match[:attributes], 'quantity') if parent_span.resource_type == :plural
+        return if parent_span.resource_type == :plural && quantity.nil?
+
+        AndroidResource.composite_key(
+          parent_span.base_key,
+          type: parent_span.resource_type,
+          quantity: quantity,
+          index: array_index
+        )
+      end
+
+      def child_span(key, start_offset, end_offset, parent_span)
+        Span.new(
+          key: key,
+          base_key: parent_span.base_key,
+          resource_type: parent_span.resource_type,
+          start_line: line_for(start_offset),
+          end_line: line_for([end_offset - 1, start_offset].max),
+          parent_start_line: parent_span.start_line,
+          parent_end_line: parent_span.end_line
+        )
+      end
+
+      def element_end(opening_match, tag, limit: @visible_content.length)
+        return [opening_match.end(0), opening_match.end(0)] if opening_match[0].rstrip.end_with?('/>')
+
+        closing = %r{</#{Regexp.escape(tag)}\s*>}.match(@visible_content, opening_match.end(0))
+        return [opening_match.end(0), opening_match.end(0)] unless closing && closing.begin(0) < limit
+
+        [closing.end(0), closing.begin(0)]
+      end
+
+      def attribute(attributes, name)
+        attributes[/\b#{Regexp.escape(name)}\s*=\s*(["'])(.*?)\1/m, 2]
+      end
+
+      def line_for(offset)
+        next_line = @line_starts.bsearch_index { |line_start| line_start > offset }
+        next_line || @line_starts.length
+      end
+
+      def mask_comments(content)
+        content
+          .gsub(/<!--.*?-->/m) { |comment| comment.gsub(/[^\n]/, ' ') }
+          .gsub(/<!\[CDATA\[.*?\]\]>/m) { |cdata| cdata.gsub(/[^\n]/, ' ') }
+      end
+    end
+    private_constant :Scanner
+  end
+end

data/lib/i18n_context_generator/apple_string_literal.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module I18nContextGenerator
+  # Shared parsing and decoding for Apple/Swift quoted string literals.
+  module AppleStringLiteral
+    BODY_PATTERN = '(?:\\\\.|[^"\\\\])*'
+    ASSIGNMENT_PATTERN = /\A\s*"(?<key>#{BODY_PATTERN})"\s*=/
+
+    module_function
+
+    def assignment_key(content)
+      match = ASSIGNMENT_PATTERN.match(content)
+      decode(match[:key]) if match
+    end
+
+    def decode(content)
+      return if content.nil?
+
+      content
+        .gsub('\\"', '"')
+        .gsub("\\'", "'")
+        .gsub('\\\\', '\\')
+        .gsub('\\n', "\n")
+        .gsub('\\r', "\r")
+        .gsub('\\t', "\t")
+    end
+  end
+end

data/lib/i18n_context_generator/cache.rb

@@ -1,15 +1,24 @@
 # frozen_string_literal: true
 
+require 'digest'
+require 'fileutils'
+require 'oj'
+require 'tempfile'
+
 module I18nContextGenerator
   # File-based cache for LLM results, keyed by translation key and source context.
   class Cache
-    CACHE_DIR = '.i18n-context-generator-cache'
+    DEFAULT_DIR = '.i18n-context-generator-cache'
+    CACHE_DIR = DEFAULT_DIR # Backward-compatible constant name.
     # Bump this when prompt format, search heuristics, or output schema change
-    CACHE_VERSION = 'v2'
+    CACHE_VERSION = 'v5'
+
+    attr_reader :directory
 
-    def initialize(enabled: true)
+    def initialize(enabled: true, directory: DEFAULT_DIR)
       @enabled = enabled
-      FileUtils.mkdir_p(CACHE_DIR) if @enabled && !File.directory?(CACHE_DIR)
+      @directory = directory
+      FileUtils.mkdir_p(@directory) if @enabled && !File.directory?(@directory)
     end
 
     def get(key, text, context: nil)
@@ -26,15 +35,21 @@ module I18nContextGenerator
 
     def set(key, text, result, context: nil)
       return unless @enabled
+      return if result[:error] || result['error']
 
       path = cache_path(key, text, context)
-      File.write(path, Oj.dump(result, indent: 2, mode: :compat))
+      write_atomically(path, Oj.dump(result, indent: 2, mode: :compat))
     rescue StandardError => e
       warn "Cache write error for #{key}: #{e.message}"
     end
 
     def clear
-      FileUtils.rm_rf(CACHE_DIR) if File.directory?(CACHE_DIR)
+      return unless File.directory?(@directory)
+
+      Dir.children(@directory).grep(/\A(?:[a-f0-9]{32}(?:[a-f0-9]{32})?\.json|context-cache-.*\.tmp)\z/).each do |filename|
+        FileUtils.rm_f(File.join(@directory, filename))
+      end
+      Dir.rmdir(@directory) if safe_to_remove_empty_directory? && Dir.empty?(@directory)
     end
 
     private
@@ -42,8 +57,25 @@ module I18nContextGenerator
     def cache_path(key, text, context)
       # Include version, key, text, and context (match locations/code) in hash
       # so cache invalidates when source code usage changes
-      hash = Digest::MD5.hexdigest("#{CACHE_VERSION}:#{key}:#{text}:#{context}")
-      File.join(CACHE_DIR, "#{hash}.json")
+      hash = Digest::SHA256.hexdigest("#{CACHE_VERSION}:#{key}:#{text}:#{context}")
+      File.join(@directory, "#{hash}.json")
+    end
+
+    def write_atomically(path, contents)
+      tempfile = Tempfile.new(['context-cache-', '.tmp'], @directory)
+      tempfile.chmod(0o600)
+      tempfile.write(contents)
+      tempfile.flush
+      tempfile.fsync
+      tempfile.close
+      File.rename(tempfile.path, path)
+    ensure
+      tempfile&.close!
+    end
+
+    def safe_to_remove_empty_directory?
+      expanded = File.expand_path(@directory)
+      ![File.expand_path(File::SEPARATOR), Dir.home, Dir.pwd].include?(expanded)
     end
   end
 end