fastlane-plugin-translate_gpt_release_notes 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 409b1bcd2c73ee2accc11399a91ffb090bbecd3ae523950e1e15583327702d9e
-  data.tar.gz: 1ee83d987e74e9dbbb2e903940cdc74eff26476ab436f0637b2ff5681dddb455
+  metadata.gz: b385f63605a33af014b3a222ecb688104e4e8a3088b14082b5c007f622ad34af
+  data.tar.gz: 546441b716377cf1e97b87fdddea9edee109df5cf7669bb5ab2aca0a5acc8f67
 SHA512:
-  metadata.gz: e64e5272e48df8a01e1a28b625d31a4c859ce7c1e3998a6116ddbb4eed11f9d157eb12e801090d3ee84e0a7175c632f86515f270a55c1e792777c0f8425236cb
-  data.tar.gz: 8f5c8d58a9ffc296c035946d303c3439877d24d39262f17231d7fd1d771054a247202ecddd91b1e6a6fc9877db3613c325bc59eec0e673e1c1f10be33fef6c87
+  metadata.gz: 1a35df216fcdff9f348c7498c1d13a1673fee2d5ca2ccd44f658d2b492402daf39b6fdd94f6f2e2446e74d7e584d3eb7ffdf3e1d72503220dc6a661718f82726
+  data.tar.gz: 7737dd4325c1e65c2b474c34da0a3facff4e1b792936aaa211074b719ba8713fd77fc31a273540a484961efb7d75ad0346fe97d7a8650270b40463c3e994165b

data/README.md

@@ -171,6 +171,109 @@ translate_gpt_release_notes(
 
 **Note**: DeepL automatically detects free vs paid API keys (free keys end with `:fx`) and uses the appropriate endpoint.
 
+## Glossary Support (Experimental)
+
+> **Note**: Glossary support is an experimental feature. If you encounter any issues, please [open an issue on GitHub](https://github.com/antonkarliner/fastlane-plugin-translate_gpt_release_notes/issues).
+
+The glossary feature ensures consistent translation of app-specific terms (screen names, feature names, UI labels) across all locales. Instead of letting the AI provider guess how to translate "Brew Diary" or "Cupping Score", the glossary provides exact translations extracted from your existing localization files.
+
+### How It Works
+
+1. The plugin loads glossary terms from a JSON file and/or a directory of localization files
+2. Before each translation, it fuzzy-matches terms from the glossary against the source text
+3. Only relevant terms are included in the translation prompt (keeping it concise)
+4. Each provider uses the glossary differently:
+   - **OpenAI**: Glossary terms are sent as a system message for strong instruction following
+   - **Anthropic / Gemini**: Glossary terms are included in the translation prompt
+   - **DeepL**: Glossary terms are passed via the `context` parameter
+
+### Supported Localization Formats
+
+| Format | Extension | Common Use |
+|--------|-----------|------------|
+| ARB (Application Resource Bundle) | `.arb` | Flutter |
+| Apple Strings | `.strings` | iOS / macOS |
+| Android XML | `.xml` | Android |
+| JSON i18n | `.json` | Web / React / Vue |
+| XLIFF | `.xliff`, `.xlf` | Cross-platform |
+
+### Using Localization Directory (Recommended)
+
+Point the plugin at your existing localization directory. It will auto-detect the format and extract terms:
+
+```ruby
+# Flutter project — use the l10n directory directly
+translate_gpt_release_notes(
+  master_locale: 'en-US',
+  platform: 'ios',
+  glossary_dir: '../lib/l10n'
+)
+
+# iOS project — use .lproj directories
+translate_gpt_release_notes(
+  master_locale: 'en-US',
+  platform: 'ios',
+  glossary_dir: '../MyApp/Resources'
+)
+
+# Android project — use res/values directories
+translate_gpt_release_notes(
+  master_locale: 'en-US',
+  platform: 'android',
+  glossary_dir: '../app/src/main/res'
+)
+```
+
+### Using a Curated JSON Glossary File
+
+For maximum control, create a JSON glossary file with exact translations per locale:
+
+```json
+{
+  "Home Screen": {
+    "de": "Startbildschirm",
+    "fr": "Ecran d'accueil",
+    "es": "Pantalla de inicio",
+    "ja": "ホーム画面"
+  },
+  "Brew Diary": {
+    "de": "Brautagebuch",
+    "fr": "Journal de brassage"
+  }
+}
+```
+
+```ruby
+translate_gpt_release_notes(
+  master_locale: 'en-US',
+  platform: 'ios',
+  glossary: 'path/to/glossary.json'
+)
+```
+
+### Combining Both Sources
+
+You can use both a curated glossary file and a localization directory. The curated file takes priority for overlapping terms:
+
+```ruby
+translate_gpt_release_notes(
+  master_locale: 'en-US',
+  platform: 'ios',
+  glossary: 'fastlane/glossary.json',
+  glossary_dir: '../lib/l10n'
+)
+```
+
+### Fuzzy Matching
+
+The plugin uses smart fuzzy matching to find relevant glossary terms in the source text:
+
+- **Full substring match**: "Home Screen" matches if it appears exactly in the text
+- **Multi-word match**: A term matches if 2 or more significant words (4+ characters, excluding common English stopwords) appear in the text
+- **Filtering**: Terms shorter than 4 characters, longer than 80 characters, or consisting of common stopwords are excluded
+
+This keeps the glossary concise and avoids flooding the AI provider with irrelevant terms.
+
 ## Options
 
 ### Core Options
@@ -181,6 +284,8 @@ translate_gpt_release_notes(
 | `master_locale` | Master language/locale for the source texts | `MASTER_LOCALE` | `en-US` |
 | `platform` | Platform (`ios` or `android`) | `PLATFORM` | `ios` |
 | `context` | Context for translation to improve accuracy | `GPT_CONTEXT` | - |
+| `glossary` | Path to a curated JSON glossary file | `GLOSSARY_PATH` | - |
+| `glossary_dir` | Path to localization files directory for auto-extracting glossary | `GLOSSARY_DIR` | - |
 
 ### Provider-Specific API Keys
 
@@ -379,6 +484,25 @@ export OPENAI_API_KEY='your-key-here'
 
 **Solution**: This is expected behavior. If speed is critical, use `service_tier: 'default'` or `service_tier: 'priority'`.
 
+### Glossary Terms Not Being Applied
+
+**Cause**: The fuzzy matching didn't find your terms in the source text.
+
+**Solutions**:
+1. Check that terms are at least 4 characters long
+2. For multi-word terms, at least 2 significant words (4+ chars, non-stopword) must appear in the text
+3. Use `glossary` with a curated JSON file for critical terms
+4. If using `glossary_dir`, verify the localization files contain translations for the target locale
+
+### Too Many Glossary Terms Matched
+
+**Cause**: The localization directory contains many short or generic terms.
+
+**Solutions**:
+1. Use a curated JSON glossary file (`glossary`) with only the most important terms instead of pointing at the full localization directory
+2. Terms longer than 80 characters (full sentences) are automatically excluded
+3. Common English stopwords are excluded from matching
+
 ## Provider Comparison Details
 
 ### When to Use Each Provider

data/lib/fastlane/plugin/translate_gpt_release_notes/actions/translate_gpt_release_notes_action.rb

@@ -227,6 +227,28 @@ module Fastlane
             description: "Context for translation to improve accuracy",
             optional: true,
             type: String
+          ),
+          FastlaneCore::ConfigItem.new(
+            key: :glossary,
+            env_name: "GLOSSARY_PATH",
+            description: "Path to a JSON glossary file with term translations per locale",
+            optional: true,
+            type: String,
+            verify_block: proc do |value|
+              next if value.nil? || value.to_s.strip.empty?
+              UI.user_error!("Glossary file not found: #{value}") unless File.exist?(value)
+            end
+          ),
+          FastlaneCore::ConfigItem.new(
+            key: :glossary_dir,
+            env_name: "GLOSSARY_DIR",
+            description: "Path to directory with localization files (ARB, .strings, .xml, .json, .xliff) for auto-extracting glossary",
+            optional: true,
+            type: String,
+            verify_block: proc do |value|
+              next if value.nil? || value.to_s.strip.empty?
+              UI.user_error!("Glossary directory not found: #{value}") unless Dir.exist?(value)
+            end
           )
         ]
       end

data/lib/fastlane/plugin/translate_gpt_release_notes/helper/glossary_loader.rb

@@ -0,0 +1,450 @@
+require 'json'
+require 'nokogiri'
+require 'loco_strings'
+require 'set'
+
+module Fastlane
+  module Helper
+    # Loads glossary terms from curated JSON files or localization directories.
+    # Supports ARB, Apple .strings, Android strings.xml, JSON i18n, and XLIFF formats.
+    # Filters terms by fuzzy matching against source text to keep prompts concise.
+    class GlossaryLoader
+      # Supported localization file extensions and their format identifiers
+      FORMAT_EXTENSIONS = {
+        '.arb' => :arb,
+        '.strings' => :strings,
+        '.xml' => :android_xml,
+        '.json' => :json,
+        '.xliff' => :xliff,
+        '.xlf' => :xliff
+      }.freeze
+
+      # Minimum word length for individual word matching in fuzzy search
+      MIN_WORD_LENGTH = 4
+
+      # Maximum term length in characters. Longer terms are full sentences/paragraphs
+      # and not useful as glossary entries for translation prompts.
+      MAX_TERM_LENGTH = 80
+
+      # Common English stopwords excluded from individual word matching.
+      # These are too generic to be useful for glossary term matching and cause
+      # excessive false positives with real-world localization files.
+      STOPWORDS = Set.new(%w[
+        about also back been come could does done each even from
+        give goes gone good have here high into just keep know
+        like long look made make many more most much must need
+        only once open over part read real right same show side
+        some such sure take than that them then they this time
+        used very want well what when will with work your
+      ]).freeze
+
+      # @param params [Hash] Plugin parameters containing glossary config
+      def initialize(params)
+        @glossary = {}
+        @source_locale = params[:master_locale] || 'en-US'
+
+        load_from_file(params[:glossary]) if params[:glossary]
+        load_from_directory(params[:glossary_dir]) if params[:glossary_dir]
+
+        if @glossary.empty?
+          UI.message("Glossary: No terms loaded")
+        else
+          UI.message("Glossary: Loaded #{@glossary.size} source terms")
+        end
+      end
+
+      # Returns glossary terms relevant to the source text for a specific target locale.
+      # Applies fuzzy matching to include only terms that appear in the source text.
+      #
+      # @param source_text [String] The release notes text being translated
+      # @param target_locale [String] Target language code (e.g., 'fr', 'de-DE')
+      # @return [Hash] Filtered hash of { source_term => target_translation }
+      def terms_for(source_text, target_locale)
+        canonical = canonicalize_locale(target_locale)
+        language_only = canonical.split('-').first
+        result = {}
+
+        @glossary.each do |source_term, locale_translations|
+          next unless fuzzy_match?(source_term, source_text)
+
+          # Try canonical locale first, then language-only, then any matching language
+          translation = locale_translations[canonical] ||
+                        locale_translations[language_only] ||
+                        find_language_match(locale_translations, language_only)
+
+          result[source_term] = translation if translation
+        end
+
+        result
+      end
+
+      private
+
+      # Loads a curated JSON glossary file.
+      # Format: { "source term": { "locale": "translation", ... }, ... }
+      #
+      # @param path [String] Path to the JSON glossary file
+      def load_from_file(path)
+        unless File.exist?(path)
+          UI.warning("Glossary file not found: #{path}")
+          return
+        end
+
+        UI.message("Glossary: Loading curated glossary from #{path}")
+        data = JSON.parse(File.read(path))
+
+        data.each do |source_term, translations|
+          next unless translations.is_a?(Hash)
+
+          @glossary[source_term] ||= {}
+          # Canonicalize locale keys so 'fr-FR', 'fr_FR', 'fr' all resolve consistently
+          translations.each do |locale, translation|
+            canonical = canonicalize_locale(locale)
+            @glossary[source_term][canonical] ||= translation
+          end
+        end
+      rescue JSON::ParserError => e
+        UI.error("Failed to parse glossary file #{path}: #{e.message}")
+      end
+
+      # Scans a directory for localization files and extracts glossary terms.
+      #
+      # @param dir [String] Path to the directory containing localization files
+      def load_from_directory(dir)
+        unless Dir.exist?(dir)
+          UI.warning("Glossary directory not found: #{dir}")
+          return
+        end
+
+        format = detect_format(dir)
+        unless format
+          UI.warning("No supported localization files found in #{dir}")
+          return
+        end
+
+        UI.message("Detected glossary format: #{format}")
+        locale_files = find_locale_files(dir, format)
+
+        source_key = find_source_locale_key(locale_files)
+        unless source_key
+          UI.warning("Source locale '#{@source_locale}' not found in #{dir}")
+          return
+        end
+
+        source_file = locale_files[source_key]
+        source_strings = parse_file(source_file, format)
+
+        locale_files.each do |locale, file_path|
+          next if locale == source_key
+
+          target_strings = parse_file(file_path, format)
+          merge_locale_strings(source_strings, target_strings, locale)
+        end
+      end
+
+      # Detects the localization format from files in the directory.
+      #
+      # @param dir [String] Directory path
+      # @return [Symbol, nil] Format identifier or nil
+      def detect_format(dir)
+        # Check for .lproj subdirectories (iOS .strings)
+        return :strings if Dir.glob(File.join(dir, '**', '*.lproj')).any?
+
+        # Check for Android values-* directories
+        return :android_xml if Dir.glob(File.join(dir, 'values*', '*.xml')).any?
+
+        # Check files by extension
+        files = Dir.glob(File.join(dir, '**', '*')).select { |f| File.file?(f) }
+        files.each do |file|
+          ext = File.extname(file).downcase
+          return FORMAT_EXTENSIONS[ext] if FORMAT_EXTENSIONS.key?(ext)
+        end
+
+        nil
+      end
+
+      # Finds locale files in the directory based on format-specific patterns.
+      #
+      # @param dir [String] Directory path
+      # @param format [Symbol] Format identifier
+      # @return [Hash] { locale_code => file_path }
+      def find_locale_files(dir, format)
+        case format
+        when :arb then find_arb_files(dir)
+        when :strings then find_strings_files(dir)
+        when :android_xml then find_android_xml_files(dir)
+        when :json then find_json_files(dir)
+        when :xliff then find_xliff_files(dir)
+        else {}
+        end
+      end
+
+      def find_arb_files(dir)
+        files = {}
+        Dir.glob(File.join(dir, '**', '*.arb')).each do |path|
+          basename = File.basename(path, '.arb')
+          # Match patterns: app_en, app_en_US, intl_en, en
+          if basename =~ /(?:^|_)([a-z]{2}(?:[_-][A-Za-z]{2,})?)$/
+            locale = canonicalize_locale(Regexp.last_match(1))
+            files[locale] = path
+          end
+        end
+        files
+      end
+
+      def find_strings_files(dir)
+        files = {}
+        Dir.glob(File.join(dir, '**', '*.lproj', '*.strings')).each do |path|
+          lproj = File.basename(File.dirname(path), '.lproj')
+          files[canonicalize_locale(lproj)] = path
+        end
+        files
+      end
+
+      def find_android_xml_files(dir)
+        files = {}
+        Dir.glob(File.join(dir, 'values*', '*.xml')).each do |path|
+          values_dir = File.basename(File.dirname(path))
+          if values_dir == 'values'
+            files['default'] = path
+          elsif values_dir =~ /^values-(.+)$/
+            locale = Regexp.last_match(1)
+            files[canonicalize_locale(locale)] = path
+          end
+        end
+        files
+      end
+
+      def find_json_files(dir)
+        files = {}
+        Dir.glob(File.join(dir, '**', '*.json')).each do |path|
+          basename = File.basename(path, '.json')
+          # Match: en.json, en-US.json, messages_en.json
+          if basename =~ /(?:^|_)([a-z]{2}(?:[_-][A-Za-z]{2,})?)$/
+            locale = canonicalize_locale(Regexp.last_match(1))
+            files[locale] = path
+          elsif basename =~ /^([a-z]{2}(?:[_-][A-Za-z]{2,})?)$/
+            locale = canonicalize_locale(Regexp.last_match(1))
+            files[locale] = path
+          end
+        end
+        files
+      end
+
+      def find_xliff_files(dir)
+        files = {}
+        Dir.glob(File.join(dir, '**', '*.{xliff,xlf}')).each do |path|
+          doc = Nokogiri::XML(File.read(path))
+          doc.remove_namespaces!
+          doc.xpath('//file').each do |file_node|
+            target_lang = file_node['target-language']
+            source_lang = file_node['source-language']
+            files[source_lang] = path if source_lang && !files.key?(source_lang)
+            files[target_lang] = path if target_lang
+          end
+        end
+        files
+      end
+
+      # Finds the source locale key in the locale files hash.
+      # Tries canonical match, then language-only, then Android default.
+      #
+      # @param locale_files [Hash] Available locale files
+      # @return [String, nil] The matching key or nil
+      def find_source_locale_key(locale_files)
+        canonical = canonicalize_locale(@source_locale)
+        language_only = canonical.split('-').first
+
+        # Canonical match (handles en-US == en_US == en-us)
+        return canonical if locale_files.key?(canonical)
+
+        # Language-only match (en-US -> en)
+        return language_only if locale_files.key?(language_only)
+
+        # Android default (values/ directory = source locale)
+        return 'default' if locale_files.key?('default')
+
+        # Last resort: any key sharing the same language
+        locale_files.keys.find { |k| k.split('-').first == language_only }
+      end
+
+      # Parses a localization file based on its format.
+      #
+      # @param path [String] File path
+      # @param format [Symbol] Format identifier
+      # @return [Hash] { key => value } pairs
+      def parse_file(path, format)
+        case format
+        when :arb then parse_arb(path)
+        when :strings, :android_xml then parse_loco_strings(path)
+        when :json then parse_json(path)
+        when :xliff then parse_xliff(path)
+        else {}
+        end
+      rescue StandardError => e
+        UI.warning("Failed to parse #{path}: #{e.message}")
+        {}
+      end
+
+      def parse_arb(path)
+        data = JSON.parse(File.read(path))
+        data.reject { |k, v| k.start_with?('@') || !v.is_a?(String) }
+      end
+
+      def parse_loco_strings(path)
+        file = LocoStrings.load(path)
+        strings = file.read
+        strings.each_with_object({}) do |(key, loco_string), hash|
+          hash[key] = loco_string.value if loco_string.respond_to?(:value) && loco_string.value
+        end
+      end
+
+      def parse_json(path)
+        data = JSON.parse(File.read(path))
+        flatten_hash(data)
+      end
+
+      def parse_xliff(path)
+        doc = Nokogiri::XML(File.read(path))
+        doc.remove_namespaces!
+        result = {}
+        doc.xpath('//trans-unit').each do |unit|
+          key = unit['id']
+          source = unit.at_xpath('source')&.text
+          target = unit.at_xpath('target')&.text
+          result[key] = { source: source, target: target } if key && source
+        end
+        result
+      end
+
+      # Flattens a nested hash into dot-separated keys.
+      #
+      # @param hash [Hash] Nested hash
+      # @param prefix [String] Key prefix for recursion
+      # @return [Hash] Flat hash with dot-separated keys
+      def flatten_hash(hash, prefix = '')
+        hash.each_with_object({}) do |(k, v), result|
+          key = prefix.empty? ? k.to_s : "#{prefix}.#{k}"
+          if v.is_a?(Hash)
+            result.merge!(flatten_hash(v, key))
+          elsif v.is_a?(String)
+            result[key] = v
+          end
+        end
+      end
+
+      # Merges parsed locale strings into the glossary.
+      # For XLIFF, uses source/target pairs directly.
+      # For other formats, maps source values to target values by key.
+      # Locale keys are canonicalized for consistent lookup.
+      #
+      # @param source_strings [Hash] Source locale key-value pairs
+      # @param target_strings [Hash] Target locale key-value pairs
+      # @param target_locale [String] Target locale code (already canonical from find_locale_files)
+      def merge_locale_strings(source_strings, target_strings, target_locale)
+        canonical_locale = canonicalize_locale(target_locale)
+
+        if xliff_format?(source_strings)
+          merge_xliff_strings(target_strings, canonical_locale)
+        else
+          source_strings.each do |key, source_value|
+            target_value = target_strings[key]
+            next unless target_value && !target_value.to_s.empty?
+            next if source_value.to_s.empty?
+
+            @glossary[source_value] ||= {}
+            # Don't overwrite curated glossary entries
+            @glossary[source_value][canonical_locale] ||= target_value
+          end
+        end
+      end
+
+      def xliff_format?(strings)
+        strings.values.first.is_a?(Hash) && strings.values.first.key?(:source)
+      end
+
+      def merge_xliff_strings(strings, target_locale)
+        strings.each do |_key, entry|
+          next unless entry.is_a?(Hash) && entry[:source] && entry[:target]
+
+          source_value = entry[:source]
+          target_value = entry[:target]
+          next if source_value.empty? || target_value.empty?
+
+          @glossary[source_value] ||= {}
+          @glossary[source_value][target_locale] ||= target_value
+        end
+      end
+
+      # Fuzzy matches a glossary term against source text.
+      # Case-insensitive substring matching + multi-word matching for significant words.
+      # For multi-word terms, at least 2 significant (non-stopword, >= 4 char) words
+      # must appear in the source text to qualify as a match.
+      #
+      # @param term [String] The glossary source term
+      # @param text [String] The source text to match against
+      # @return [Boolean] Whether the term matches
+      def fuzzy_match?(term, text)
+        return false if term.nil? || text.nil?
+        return false if term.length < MIN_WORD_LENGTH
+        return false if term.length > MAX_TERM_LENGTH
+
+        # Ensure consistent UTF-8 encoding for comparison
+        downcased_text = text.encode('UTF-8', invalid: :replace, undef: :replace).downcase
+        downcased_term = term.encode('UTF-8', invalid: :replace, undef: :replace).downcase
+
+        # Full term substring match (case-insensitive)
+        return true if downcased_text.include?(downcased_term)
+
+        # Multi-word matching: require at least 2 significant words to match
+        words = downcased_term.split(/\s+/)
+        return false if words.length <= 1
+
+        significant_matches = words.count do |word|
+          word.length >= MIN_WORD_LENGTH && !STOPWORDS.include?(word) && downcased_text.include?(word)
+        end
+
+        significant_matches >= 2
+      end
+
+      # Canonicalizes a locale code to a consistent format.
+      # Handles various conventions: underscores, hyphens, Android 'r' prefix,
+      # and case differences. Output is lowercase with hyphens.
+      #
+      # Examples:
+      #   'en-US'   -> 'en-us'
+      #   'en_US'   -> 'en-us'
+      #   'en'      -> 'en'
+      #   'en-rUS'  -> 'en-us'   (Android resource qualifier)
+      #   'zh-Hans' -> 'zh-hans'
+      #   'zh_Hant_TW' -> 'zh-hant-tw'
+      #   'default' -> 'default' (Android values/ special case)
+      #
+      # @param locale [String] Locale code in any common format
+      # @return [String] Canonical lowercase hyphen-separated locale
+      def canonicalize_locale(locale)
+        code = locale.to_s.strip
+        return code if code == 'default'
+
+        # Normalize separators: underscores to hyphens
+        code = code.tr('_', '-')
+
+        # Remove Android 'r' prefix from region codes (e.g., 'en-rUS' -> 'en-US')
+        code = code.gsub(/\b([a-zA-Z]{2})-r([A-Z]{2})\b/, '\1-\2')
+
+        code.downcase
+      end
+
+      # Finds a matching translation for a target locale by language code.
+      # Used as a fallback when exact and language-only matches fail.
+      # For example, glossary has 'fr-fr' but target is 'fr-ca'.
+      #
+      # @param translations [Hash] Available translations { locale => text }
+      # @param language [String] Language code (e.g., 'fr', 'de')
+      # @return [String, nil] Matching translation or nil
+      def find_language_match(translations, language)
+        translations.find { |locale, _| locale.split('-').first == language }&.last
+      end
+    end
+  end
+end

data/lib/fastlane/plugin/translate_gpt_release_notes/helper/providers/anthropic_provider.rb

@@ -79,13 +79,14 @@ module Fastlane
         # @param text [String] The text to translate
         # @param source_locale [String] Source language code (e.g., 'en', 'de')
         # @param target_locale [String] Target language code (e.g., 'es', 'fr')
+        # @param glossary_terms [Hash] Optional glossary { source_term => target_translation }
         # @return [String, nil] Translated text or nil on error
-        def translate(text, source_locale, target_locale)
-          # Build prompt using inherited method
-          prompt = build_prompt(text, source_locale, target_locale)
+        def translate(text, source_locale, target_locale, glossary_terms: {})
+          # Build prompt using inherited method (includes instructions, glossary, and text)
+          prompt = build_prompt(text, source_locale, target_locale, glossary_terms: glossary_terms)
 
-          # Add Android limitations if needed
-          prompt = apply_android_limitations(prompt) if @params[:platform] == 'android'
+          # Add Android limitations if needed (appended after the text)
+          prompt += "\n\n" + android_limitation_instruction if @params[:platform] == 'android'
 
           # Make API call using ruby-anthropic gem API
           response = @client.complete(

data/lib/fastlane/plugin/translate_gpt_release_notes/helper/providers/base_provider.rb

@@ -26,8 +26,9 @@ module Fastlane
         # @param text [String] The text to translate
         # @param source_locale [String] Source language code (e.g., 'en', 'de')
         # @param target_locale [String] Target language code (e.g., 'es', 'fr')
+        # @param glossary_terms [Hash] Optional glossary { source_term => target_translation }
         # @return [String, nil] Translated text or nil on error
-        def translate(text, source_locale, target_locale)
+        def translate(text, source_locale, target_locale, glossary_terms: {})
           raise NotImplementedError, "#{self.class.name} must implement #translate"
         end
 
@@ -83,19 +84,20 @@ module Fastlane
         protected
 
         # Builds a translation prompt for the AI provider.
-        # Includes context about platform limitations if applicable.
+        # Structure: instructions first, context/glossary in the middle, text to translate last.
+        # This ordering ensures the model reads all constraints before processing the text.
         #
         # @param text [String] The text to translate
         # @param source_locale [String] Source language code
         # @param target_locale [String] Target language code
+        # @param glossary_terms [Hash] Optional glossary { source_term => target_translation }
         # @return [String] The formatted prompt
-        def build_prompt(text, source_locale, target_locale)
+        def build_prompt(text, source_locale, target_locale, glossary_terms: {})
           prompt_parts = []
 
-          # Base translation instruction
-          prompt_parts << "Translate the following text from #{source_locale} to #{target_locale}:"
-          prompt_parts << ""
-          prompt_parts << "\"#{text}\""
+          # Instructions first: role, task, and output format
+          prompt_parts << "Translate the following release notes from #{source_locale} to #{target_locale}."
+          prompt_parts << "Respond with ONLY the translated text. Preserve the original formatting, line breaks, and bullet points."
 
           # Add context if provided
           if @params[:context]
@@ -103,23 +105,69 @@ module Fastlane
             prompt_parts << "Context: #{@params[:context]}"
           end
 
-          # Apply Android limitations if specified
-          if @params[:android_limitations]
+          # Add glossary terms before the text so the model reads them first
+          unless glossary_terms.nil? || glossary_terms.empty?
             prompt_parts << ""
-            prompt_parts << apply_android_limitations("")
+            prompt_parts << "Use the following glossary for consistent terminology. Apply these exact translations for the specified terms:"
+            glossary_terms.each do |source_term, target_term|
+              prompt_parts << "- \"#{source_term}\" -> \"#{target_term}\""
+            end
           end
 
+          # Text to translate last, so the model processes it with full context
+          prompt_parts << ""
+          prompt_parts << "Text to translate:"
+          prompt_parts << text
+
           prompt_parts.join("\n")
         end
 
+        # Builds a system instruction for providers that support separate system/user messages.
+        # Contains all translation rules, context, and glossary — but NOT the text to translate.
+        # Used by OpenAI (system message). Other providers use build_prompt which combines everything.
+        #
+        # @param source_locale [String] Source language code
+        # @param target_locale [String] Target language code
+        # @param glossary_terms [Hash] Optional glossary { source_term => target_translation }
+        # @return [String] The system instruction
+        def build_system_instruction(source_locale, target_locale, glossary_terms: {})
+          parts = []
+
+          parts << "Translate the following release notes from #{source_locale} to #{target_locale}."
+          parts << "Respond with ONLY the translated text. Preserve the original formatting, line breaks, and bullet points."
+
+          if @params[:context]
+            parts << ""
+            parts << "Context: #{@params[:context]}"
+          end
+
+          unless glossary_terms.nil? || glossary_terms.empty?
+            parts << ""
+            parts << "Use the following glossary for consistent terminology. Apply these exact translations for the specified terms:"
+            glossary_terms.each do |source_term, target_term|
+              parts << "- \"#{source_term}\" -> \"#{target_term}\""
+            end
+          end
+
+          parts.join("\n")
+        end
+
+        # Returns the Android character limitation instruction as a standalone string.
+        # Used by providers that build messages separately (e.g., OpenAI with system/user split).
+        #
+        # @return [String] The Android limitation instruction
+        def android_limitation_instruction
+          "IMPORTANT: The translated text must not exceed #{ANDROID_CHAR_LIMIT} characters " \
+          "(Google Play Store release notes limit). Provide a concise translation."
+        end
+
         # Adds Android character limit constraint to the prompt.
         # Google Play has a 500 character limit for release notes.
         #
         # @param prompt [String] The existing prompt to append to
         # @return [String] The prompt with limitation instruction appended
         def apply_android_limitations(prompt)
-          prompt + "IMPORTANT: The translated text must not exceed #{ANDROID_CHAR_LIMIT} characters " \
-          "(Google Play Store release notes limit). Please provide a concise translation."
+          prompt + android_limitation_instruction
         end
 
         # Adds a configuration error to the errors list.

data/lib/fastlane/plugin/translate_gpt_release_notes/helper/providers/deepl_provider.rb

@@ -89,8 +89,9 @@ module Fastlane
         # @param text [String] The text to translate
         # @param source_locale [String] Source language code (e.g., 'en-US', 'de-DE')
         # @param target_locale [String] Target language code (e.g., 'es', 'fr')
+        # @param glossary_terms [Hash] Optional glossary { source_term => target_translation }
         # @return [String, nil] Translated text or nil on error
-        def translate(text, source_locale, target_locale)
+        def translate(text, source_locale, target_locale, glossary_terms: {})
           # DeepL uses ISO 639-1 language codes (2-letter codes)
           # Convert locales like 'en-US' to 'EN'
           source_lang = normalize_locale(source_locale)
@@ -103,11 +104,17 @@ module Fastlane
           formality = @params[:formality].to_s.strip
           options[:formality] = formality unless formality.empty? || formality == 'default'
 
-          # DeepL supports context parameter for better translations
-          if @params[:context] && !@params[:context].empty?
-            options[:context] = @params[:context]
+          # Build context from user-provided context and glossary terms
+          context_parts = []
+          context_parts << @params[:context] if @params[:context] && !@params[:context].empty?
+
+          if glossary_terms && !glossary_terms.empty?
+            glossary_str = glossary_terms.map { |s, t| "#{s} = #{t}" }.join("; ")
+            context_parts << "Glossary: #{glossary_str}"
           end
 
+          options[:context] = context_parts.join(". ") unless context_parts.empty?
+
           # Make API call
           result = DeepL.translate(text, source_lang, target_lang, options)
 

data/lib/fastlane/plugin/translate_gpt_release_notes/helper/providers/gemini_provider.rb

@@ -76,13 +76,14 @@ module Fastlane
         # @param text [String] The text to translate
         # @param source_locale [String] Source language code (e.g., 'en', 'de')
         # @param target_locale [String] Target language code (e.g., 'es', 'fr')
+        # @param glossary_terms [Hash] Optional glossary { source_term => target_translation }
         # @return [String, nil] Translated text or nil on error
-        def translate(text, source_locale, target_locale)
-          # Build prompt using inherited method
-          prompt = build_prompt(text, source_locale, target_locale)
+        def translate(text, source_locale, target_locale, glossary_terms: {})
+          # Build prompt using inherited method (includes instructions, glossary, and text)
+          prompt = build_prompt(text, source_locale, target_locale, glossary_terms: glossary_terms)
 
-          # Add Android limitations if needed
-          prompt = apply_android_limitations(prompt) if @params[:platform] == 'android'
+          # Add Android limitations if needed (appended after the text)
+          prompt += "\n\n" + android_limitation_instruction if @params[:platform] == 'android'
 
           # Make API call
           result = make_api_request(prompt)

data/lib/fastlane/plugin/translate_gpt_release_notes/helper/providers/openai_provider.rb

@@ -72,22 +72,31 @@ module Fastlane
         end
 
         # Translates text from source locale to target locale using OpenAI's API.
+        # Uses a system message for instructions and a user message for the text,
+        # which improves instruction following for glossary terms and output format.
         #
         # @param text [String] The text to translate
         # @param source_locale [String] Source language code (e.g., 'en', 'de')
         # @param target_locale [String] Target language code (e.g., 'es', 'fr')
+        # @param glossary_terms [Hash] Optional glossary { source_term => target_translation }
         # @return [String, nil] Translated text or nil on error
-        def translate(text, source_locale, target_locale)
-          # Build prompt using inherited build_prompt method
-          prompt = build_prompt(text, source_locale, target_locale)
-
-          # Add Android limitations if needed
-          prompt = apply_android_limitations(prompt) if @params[:platform] == 'android'
+        def translate(text, source_locale, target_locale, glossary_terms: {})
+          # Build system instruction and user content separately for better results
+          system_instruction = build_system_instruction(source_locale, target_locale, glossary_terms: glossary_terms)
+          user_content = text
+
+          # Add Android limitations to system instruction if needed
+          if @params[:platform] == 'android'
+            system_instruction += "\n\n" + android_limitation_instruction
+          end
 
-          # Build parameters hash
+          # Build parameters hash with separate system and user messages
           parameters = {
             model: @params[:model_name] || DEFAULT_MODEL,
-            messages: [{ role: 'user', content: prompt }],
+            messages: [
+              { role: 'system', content: system_instruction },
+              { role: 'user', content: user_content }
+            ],
             temperature: (@params[:temperature] || DEFAULT_TEMPERATURE).to_f
           }
 

data/lib/fastlane/plugin/translate_gpt_release_notes/helper/translate_gpt_release_notes_helper.rb

@@ -1,5 +1,6 @@
 require 'fastlane_core/ui/ui'
 require_relative 'providers/provider_factory'
+require_relative 'glossary_loader'
 
 module Fastlane
   UI = FastlaneCore::UI unless Fastlane.const_defined?("UI")
@@ -23,12 +24,24 @@ module Fastlane
         unless @provider.valid?
           UI.user_error!("Provider configuration errors: #{@provider.config_errors.join(', ')}")
         end
+
+        # Initialize glossary loader if glossary parameters are provided
+        if params[:glossary] || params[:glossary_dir]
+          @glossary_loader = GlossaryLoader.new(params)
+          UI.message("Glossary sources: #{[params[:glossary] && 'file', params[:glossary_dir] && 'directory'].compact.join(' + ')}")
+        end
       end
 
       # Request a translation from the configured provider
       def translate_text(text, target_locale, _platform)
         source_locale = @params[:master_locale]
-        @provider.translate(text, source_locale, target_locale)
+        glossary_terms = @glossary_loader&.terms_for(text, target_locale) || {}
+
+        if glossary_terms.any?
+          UI.message("Glossary: #{glossary_terms.size} terms matched for #{target_locale}")
+        end
+
+        @provider.translate(text, source_locale, target_locale, glossary_terms: glossary_terms)
       end
 
       # Sleep for a specified number of seconds, displaying a progress bar

data/lib/fastlane/plugin/translate_gpt_release_notes/version.rb

@@ -1,5 +1,5 @@
 module Fastlane
   module TranslateGptReleaseNotes
-    VERSION = "0.2.0"
+    VERSION = "0.3.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fastlane-plugin-translate_gpt_release_notes
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Anton Karliner
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-01-29 00:00:00.000000000 Z
+date: 2026-03-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby-openai
@@ -245,6 +245,7 @@ files:
 - lib/fastlane/plugin/translate_gpt_release_notes.rb
 - lib/fastlane/plugin/translate_gpt_release_notes/actions/translate_gpt_release_notes_action.rb
 - lib/fastlane/plugin/translate_gpt_release_notes/helper/credential_resolver.rb
+- lib/fastlane/plugin/translate_gpt_release_notes/helper/glossary_loader.rb
 - lib/fastlane/plugin/translate_gpt_release_notes/helper/providers/anthropic_provider.rb
 - lib/fastlane/plugin/translate_gpt_release_notes/helper/providers/base_provider.rb
 - lib/fastlane/plugin/translate_gpt_release_notes/helper/providers/deepl_provider.rb