fastlane-plugin-translate 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d4b55852f8515ef6942b0bf6819379eb2c3cb81e20ef872a924470a2e9b6d886
-  data.tar.gz: 7d1d3b603837c68bd8fd548dca30b171ff074e42218956b910f9446109a3fea2
+  metadata.gz: '094cd9a767279fbff36838d5bea6a4adb7e6f64381df5cf2ae934e1a37c7038e'
+  data.tar.gz: f0de0b5a62196fc84570c1d8cd44651b16a75193f9659ac4eca2baea203ade18
 SHA512:
-  metadata.gz: 83b931afb04769b0d6bd57fe7b686a772e707d350239dbcef6d191633078d2cd205f5ebf2f0229a88aab838ef824dd078f3326b7489ed633bd6462af633d3e91
-  data.tar.gz: 1be7fd87de5af70a4ea87a8c05fc8900606e3fa07327c2f0694997a0f614163be7fdcec98c170ad7e4d2bee798d53b4d396838ec57fd398c603fcf7fec9f67a1
+  metadata.gz: 75d924a65adfdb29515f747fb4513eed4bdc85eec3d378c299656f7aaecb0934e1ec33494714a2e4296141a0d6b2478083b02b5b1dc01fa2a2bfb9df9abfacfa
+  data.tar.gz: 0cca73dcf50da91a43bb3ff19e838ff0da44331e8a44b6e32551009d824516c29e87873750bc3a46d7b0ef4dc700d54567b943f81551854fd4866977a1b9fcec

data/README.md

@@ -5,6 +5,7 @@
 </div>
 
 [![fastlane Plugin Badge](https://rawcdn.githack.com/fastlane/fastlane/master/fastlane/assets/plugin-badge.svg)](https://rubygems.org/gems/fastlane-plugin-translate)
+[![Gem Version](https://badge.fury.io/rb/fastlane-plugin-translate.svg)](https://badge.fury.io/rb/fastlane-plugin-translate)
 [![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-support-yellow.svg?style=flat)](https://buymeacoffee.com/xocrgwybbs)
 
 ## About translate
@@ -13,16 +14,13 @@ Automatically translate iOS `Localizable.xcstrings` files using DeepL API. This
 
 ## Features
 
-- 🔍 **Auto-discovery**: Automatically finds your `Localizable.xcstrings` file
-- 📊 **Translation analysis**: Shows translation progress for each language
-- 🎯 **Smart targeting**: Only translates untranslated strings (state: "new" with empty values)
-- 💾 **Progress tracking**: Saves progress between runs to avoid re-translating
-- 🎭 **Formality support**: Automatically detects and offers formality options for supported languages
-- 📝 **Context extraction**: Uses comments from xcstrings as translation context
-- 🔄 **Batch processing**: Efficiently handles large numbers of strings
-- 🛡️ **Error recovery**: Comprehensive error handling with user choices
-- 📄 **Automatic backups**: Creates timestamped backups before translation
-- ✅ **Validation**: Ensures output file is valid JSON
+- **Language selection with progress**: Shows translation completeness for each language
+- **Smart targeting**: Only translates missing strings, preserves existing translations
+- **Formality options**: Formal/informal translation styles for supported languages
+- **Context-aware translation**: Uses xcstrings comments to improve translation quality
+- **Progress tracking**: Resume interrupted translations without starting over
+- **Automatic backups**: Safe translation with rollback capability
+- **Error recovery**: Handle API failures gracefully with retry options
 
 ## Getting Started
 
@@ -59,9 +57,29 @@ bundle install
 
 ### Basic Usage
 
+After installation, create a lane in your Fastfile and run it:
+
+```bash
+fastlane ios translate
+```
+
+**Simple dedicated lane:**
+
 ```ruby
-# Automatically detect xcstrings file and show language selection
-translate_with_deepl
+lane :translate do
+  translate_with_deepl
+end
+```
+
+**Within complex workflows:**
+
+```ruby
+lane :prepare_release do
+  build_app
+  translate_with_deepl(target_language: "de")
+  upload_to_testflight
+  slack(message: "New build with German translations available!")
+end
 ```
 
 ### Specify Target Language

data/lib/fastlane/plugin/translate/actions/translate_with_deepl.rb

@@ -17,6 +17,7 @@ module Fastlane
         # Setup and validation
         setup_deepl_client(params)
         xcstrings_path = find_xcstrings_file(params[:xcstrings_path])
+
         backup_file = create_backup(xcstrings_path)
 
         # Parse xcstrings file
@@ -144,12 +145,36 @@ module Fastlane
         # Sort by most untranslated first (prioritize languages that need work)
         language_options.sort_by! { |opt| -opt[:stats][:untranslated] }
 
+        # Show all languages with their translation status
         UI.message('📋 Available languages for translation:')
-        selected_display = UI.select('Choose target language:', language_options.map { |opt| opt[:display] })
 
-        # Find the corresponding language code
-        selected_option = language_options.find { |opt| opt[:display] == selected_display }
-        selected_option[:code]
+        # Display numbered list
+        language_options.each_with_index do |option, index|
+          UI.message("  #{index + 1}. #{option[:display]}")
+        end
+
+        # Force interactive mode and ensure we wait for user input
+        $stdout.flush
+        $stderr.flush
+
+        # Use a loop to ensure we get valid input
+        loop do
+          choice = UI.input("Choose target language (1-#{language_options.count}): ").strip
+
+          # Validate numeric input
+          if choice.match?(/^\d+$/)
+            choice_num = choice.to_i
+            if choice_num >= 1 && choice_num <= language_options.count
+              selected_option = language_options[choice_num - 1]
+              UI.message("✅ Selected: #{selected_option[:display]}")
+              return selected_option[:code]
+            end
+          end
+
+          UI.error("❌ Invalid selection '#{choice}'. Please enter a number between 1 and #{language_options.count}.")
+        rescue Interrupt
+          UI.user_error!('👋 Translation cancelled by user')
+        end
       end
 
       def self.calculate_translation_stats(xcstrings_data, languages)
@@ -161,8 +186,8 @@ module Fastlane
           skipped_dont_translate = 0
 
           xcstrings_data['strings'].each do |string_key, string_data|
+            # Skip empty string keys as they're usually not real translatable content
             next if string_key.empty?
-            next unless string_data.dig('localizations', lang_code)
 
             # Skip strings marked as "Don't translate" from statistics
             if string_data['shouldTranslate'] == false
@@ -170,11 +195,27 @@ module Fastlane
               next
             end
 
-            total += 1
+            # Check if this string has any localizations at all
+            if !string_data['localizations'] || string_data['localizations'].empty?
+              # String has no localizations - count as untranslated for this language
+              total += 1
+              next
+            end
+
+            # Check if this string has a localization for the target language
             localization = string_data.dig('localizations', lang_code, 'stringUnit')
+            unless localization
+              # String exists but has no localization for this specific language - count as untranslated
+              total += 1
+              next
+            end
 
-            if localization && localization['state'] == 'translated' &&
-               localization['value'] && !localization['value'].empty?
+            total += 1
+
+            # Count as translated ONLY if state is 'translated' AND has non-empty value
+            # Strings with state 'new', 'needs_review', or empty values are untranslated
+            if localization['state'] == 'translated' &&
+               localization['value'] && !localization['value'].strip.empty?
               translated += 1
             end
           end
@@ -195,16 +236,41 @@ module Fastlane
         return nil unless Helper::DeeplLanguageMapperHelper.supports_formality?(target_language)
 
         lang_name = Helper::LanguageRegistryHelper.language_name(target_language)
-        choice = UI.select(
-          "🎭 #{lang_name} supports formality options. Choose style:",
-          ['default', 'more (formal)', 'less (informal)', 'prefer_more (formal if possible)', 'prefer_less (informal if possible)']
-        )
+        options = [
+          { display: 'default (no formality preference)', value: nil },
+          { display: 'more (formal)', value: 'more' },
+          { display: 'less (informal)', value: 'less' },
+          { display: 'prefer_more (formal if possible)', value: 'prefer_more' },
+          { display: 'prefer_less (informal if possible)', value: 'prefer_less' }
+        ]
 
-        case choice
-        when 'more (formal)' then 'more'
-        when 'less (informal)' then 'less'
-        when 'prefer_more (formal if possible)' then 'prefer_more'
-        when 'prefer_less (informal if possible)' then 'prefer_less'
+        # Display numbered list
+        UI.message("🎭 #{lang_name} supports formality options. Choose style:")
+        options.each_with_index do |option, index|
+          UI.message("  #{index + 1}. #{option[:display]}")
+        end
+
+        # Force interactive mode and ensure we wait for user input
+        $stdout.flush
+        $stderr.flush
+
+        # Use a loop to ensure we get valid input
+        loop do
+          choice = UI.input("Choose formality style (1-#{options.count}): ").strip
+
+          # Validate numeric input
+          if choice.match?(/^\d+$/)
+            choice_num = choice.to_i
+            if choice_num >= 1 && choice_num <= options.count
+              selected_option = options[choice_num - 1]
+              UI.message("✅ Selected: #{selected_option[:display]}")
+              return selected_option[:value]
+            end
+          end
+
+          UI.error("❌ Invalid selection '#{choice}'. Please enter a number between 1 and #{options.count}.")
+        rescue Interrupt
+          UI.user_error!('👋 Translation cancelled by user')
         end
       end
 
@@ -224,8 +290,34 @@ module Fastlane
         if progress.has_progress?
           summary = progress.progress_summary
           UI.message("📈 Found existing progress: #{summary[:translated_count]} strings translated")
-          choice = UI.select('Continue from where you left off?', ['Yes, continue', 'No, start fresh'])
-          progress.cleanup if choice == 'No, start fresh'
+
+          # Display numbered options
+          UI.message('Continue from where you left off?')
+          UI.message('  1. Yes, continue')
+          UI.message('  2. No, start fresh')
+
+          # Force interactive mode and ensure we wait for user input
+          $stdout.flush
+          $stderr.flush
+
+          # Use a loop to ensure we get valid input
+          loop do
+            choice = UI.input('Choose option (1-2): ').strip
+
+            case choice
+            when '1'
+              UI.message('✅ Continuing from existing progress')
+              break
+            when '2'
+              UI.message('✅ Starting fresh')
+              progress.cleanup
+              break
+            else
+              UI.error("❌ Invalid selection '#{choice}'. Please enter 1 or 2.")
+            end
+          rescue Interrupt
+            UI.user_error!('👋 Translation cancelled by user')
+          end
         end
 
         # Extract untranslated strings
@@ -270,21 +362,45 @@ module Fastlane
             next
           end
 
+          # Skip if already translated in progress
+          next if already_translated[string_key]
+
+          # Check if this string has any localizations at all
+          if !string_data['localizations'] || string_data['localizations'].empty?
+            # String has no localizations - it's completely new and needs translation
+            # Use the string key itself as the source text since there's no source localization
+            untranslated[string_key] = {
+              'source_text' => string_key,
+              'context' => extract_string_context(string_key, string_data)
+            }
+            next
+          end
+
+          # Check if target language has a localization
           localization = string_data.dig('localizations', target_language, 'stringUnit')
-          next unless localization
+          unless localization
+            # String exists but has no localization for target language
+            # Get source text from source language or use string key as fallback
+            source_text = string_data.dig('localizations', source_language, 'stringUnit', 'value')
+            source_text = string_key if source_text.nil? || source_text.strip.empty?
+
+            untranslated[string_key] = {
+              'source_text' => source_text,
+              'context' => extract_string_context(string_key, string_data)
+            }
+            next
+          end
 
           # Check if NOT fully translated (inverse of the translation stats logic)
           # A string is considered translated only if: state == 'translated' AND has non-empty value
           is_fully_translated = localization['state'] == 'translated' &&
-                                localization['value'] && !localization['value'].empty?
+                                localization['value'] && !localization['value'].strip.empty?
           next if is_fully_translated
 
-          # Skip if already translated in progress
-          next if already_translated[string_key]
-
           # Get source text from source language
           source_text = string_data.dig('localizations', source_language, 'stringUnit', 'value')
-          next if source_text.nil? || source_text.empty?
+          # Use string key as fallback if no source text available
+          source_text = string_key if source_text.nil? || source_text.strip.empty?
 
           context = extract_string_context(string_key, string_data)
           untranslated[string_key] = {
@@ -312,45 +428,19 @@ module Fastlane
         batches.each_with_index do |batch, index|
           UI.message("🔄 Translating batch #{index + 1}/#{batches.count} (#{batch.count} strings)...")
 
-          # Prepare batch for DeepL API
-          texts_to_translate = batch.map { |_, data| data['source_text'] }
-
           retry_count = 0
           max_retries = 3
 
           begin
-            # Build translation options (exclude source_lang and target_lang)
-            translation_options = {}
-            translation_options[:formality] = formality if formality
-
-            # Get context from first item if available (DeepL applies to all)
-            first_context = batch.first&.last&.dig('context')
-            translation_options[:context] = first_context if first_context
-
-            # Call DeepL with positional arguments for source_lang and target_lang
-            translations = DeepL.translate(texts_to_translate, source_lang, target_lang, translation_options)
-
-            # Save translations to progress (only save non-empty translations)
-            translated_batch = {}
-            skipped_empty = 0
-
-            batch.each_with_index do |(string_key, _), text_index|
-              translated_text = translations.is_a?(Array) ? translations[text_index].text : translations.text
-
-              # Only save non-empty translations
-              if translated_text && !translated_text.strip.empty?
-                translated_batch[string_key] = translated_text
-              else
-                skipped_empty += 1
-                UI.important("⚠️ Skipping empty translation for: \"#{string_key}\"")
-              end
-            end
+            # Process the batch using the helper
+            result = Helper::BatchTranslationProcessor.process_batch(
+              batch, source_lang, target_lang, formality, progress
+            )
 
-            progress.save_translated_strings(translated_batch)
-            total_translated += translated_batch.size
+            total_translated += result[:translated_count]
 
-            success_msg = "✅ Batch #{index + 1} completed (#{translated_batch.size} strings translated"
-            success_msg += ", #{skipped_empty} empty translations skipped" if skipped_empty.positive?
+            success_msg = "✅ Batch #{index + 1} completed (#{result[:translated_count]} strings translated"
+            success_msg += ", #{result[:skipped_count]} empty translations skipped" if result[:skipped_count].positive?
             success_msg += ')'
             UI.success(success_msg)
           rescue DeepL::Exceptions::AuthorizationFailed
@@ -358,19 +448,25 @@ module Fastlane
           rescue DeepL::Exceptions::QuotaExceeded
             UI.user_error!('❌ DeepL quota exceeded. Upgrade your plan or wait for reset.')
           rescue DeepL::Exceptions::LimitExceeded
-            action = handle_rate_limit_error(batch, index, batches.count)
-            if action == :retry && retry_count < max_retries
+            action = Helper::TranslationErrorHandler.handle_rate_limit_error(batch, index, batches.count)
+            result = Helper::TranslationErrorHandler.handle_batch_result(action, retry_count, max_retries)
+
+            case result
+            when :retry
               retry_count += 1
               retry
-            elsif action == :skip
+            when :skip
               next
             end
           rescue StandardError => e
-            action = handle_translation_error(e, batch, index, batches.count)
-            if action == :retry && retry_count < max_retries
+            action = Helper::TranslationErrorHandler.handle_translation_error(e, batch, index, batches.count)
+            result = Helper::TranslationErrorHandler.handle_batch_result(action, retry_count, max_retries)
+
+            case result
+            when :retry
               retry_count += 1
               retry
-            elsif action == :skip
+            when :skip
               next
             end
           end
@@ -379,63 +475,46 @@ module Fastlane
         total_translated
       end
 
-      def self.handle_rate_limit_error(_batch, index, total_batches)
-        choice = UI.select("⚠️ Rate limit exceeded for batch #{index + 1}/#{total_batches}",
-                           ['Wait 60s and retry', 'Skip this batch', 'Abort translation'])
-        case choice
-        when 'Wait 60s and retry'
-          UI.message('⏳ Waiting 60 seconds...')
-          sleep(60)
-          :retry
-        when 'Skip this batch'
-          UI.important("⏭️ Skipping batch #{index + 1}")
-          :skip
-        when 'Abort translation'
-          UI.user_error!('❌ Translation aborted by user')
-        end
-      end
-
-      def self.handle_translation_error(error, _batch, index, total_batches)
-        UI.error("❌ Translation error for batch #{index + 1}/#{total_batches}: #{error.message}")
-        choice = UI.select('Choose action:', ['Skip this batch', 'Retry batch', 'Abort translation'])
-
-        case choice
-        when 'Skip this batch'
-          UI.important("⏭️ Skipping batch #{index + 1}")
-          :skip
-        when 'Retry batch'
-          UI.message("🔄 Retrying batch #{index + 1}")
-          :retry
-        when 'Abort translation'
-          UI.user_error!('❌ Translation aborted by user')
-        end
-      end
-
       def self.update_xcstrings_file(xcstrings_path, xcstrings_data, target_language, translated_strings)
         UI.message("📝 Updating xcstrings file with #{translated_strings.size} translations...")
 
         # Update the JSON structure
         actually_updated = 0
+        empty_translations = 0
         translated_strings.each do |string_key, translated_text|
-          localization = xcstrings_data.dig('strings', string_key, 'localizations', target_language, 'stringUnit')
-          next unless localization
+          # Ensure the string exists in the xcstrings structure
+          xcstrings_data['strings'][string_key] ||= {}
+          string_data = xcstrings_data['strings'][string_key]
+
+          # Ensure localizations structure exists
+          string_data['localizations'] ||= {}
+
+          # Ensure target language localization exists
+          string_data['localizations'][target_language] ||= {}
+
+          # Ensure stringUnit exists
+          string_data['localizations'][target_language]['stringUnit'] ||= {}
+
+          localization = string_data['localizations'][target_language]['stringUnit']
 
           # Double-check: only mark as translated if we have actual content
           if translated_text && !translated_text.strip.empty?
             localization['value'] = translated_text
             localization['state'] = 'translated'
             actually_updated += 1
+            UI.message("✅ Updated \"#{string_key}\" -> \"#{translated_text}\"")
           else
             # Keep as 'new' if translation is empty
             localization['value'] = translated_text || ''
             localization['state'] = 'new'
-            UI.important("⚠️ Keeping empty translation as 'new' state: \"#{string_key}\"")
+            empty_translations += 1
+            UI.important("⚠️ Empty translation for \"#{string_key}\" (received: \"#{translated_text || 'nil'}\")")
           end
         end
 
         # Write updated JSON back to file
         File.write(xcstrings_path, JSON.pretty_generate(xcstrings_data))
-        UI.success("💾 Updated xcstrings file (#{actually_updated} marked as translated)")
+        UI.success("💾 Updated xcstrings file (#{actually_updated} marked as translated, #{empty_translations} empty)")
       end
 
       def self.validate_json_file(xcstrings_path)
@@ -492,7 +571,7 @@ module Fastlane
           FastlaneCore::ConfigItem.new(
             key: :free_api,
             description: 'Use DeepL Free API endpoint instead of Pro',
-            type: Boolean,
+            is_string: false,
             default_value: false
           ),
           FastlaneCore::ConfigItem.new(

data/lib/fastlane/plugin/translate/helper/batch_translation_processor.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'deepl'
+require 'fastlane_core/ui/ui'
+
+module Fastlane
+  UI = FastlaneCore::UI unless Fastlane.const_defined?(:UI)
+
+  module Helper
+    class BatchTranslationProcessor
+      def self.process_batch(batch, source_lang, target_lang, formality, progress)
+        # Prepare batch for DeepL API
+        texts_to_translate = batch.map { |_, data| data['source_text'] }
+
+        # Build translation options
+        translation_options = build_translation_options(formality, batch)
+
+        # Call DeepL API
+        translations = DeepL.translate(texts_to_translate, source_lang, target_lang, translation_options)
+
+        # Process and save translations
+        save_batch_translations(batch, translations, progress)
+      end
+
+      def self.build_translation_options(formality, batch)
+        translation_options = {}
+        translation_options[:formality] = formality if formality
+
+        # Get context from first item if available (DeepL applies to all)
+        first_context = batch.first&.last&.dig('context')
+        translation_options[:context] = first_context if first_context
+
+        translation_options
+      end
+
+      def self.save_batch_translations(batch, translations, progress)
+        translated_batch = {}
+        skipped_empty = 0
+
+        batch.each_with_index do |(string_key, _), text_index|
+          translated_text = translations.is_a?(Array) ? translations[text_index].text : translations.text
+
+          # Save all translations, including empty ones - let the update logic handle them
+          translated_batch[string_key] = translated_text || ''
+
+          # Count empty translations for reporting
+          if !translated_text || translated_text.strip.empty?
+            skipped_empty += 1
+            UI.important("⚠️ DeepL returned empty translation for: \"#{string_key}\"")
+          end
+        end
+
+        progress.save_translated_strings(translated_batch)
+
+        {
+          translated_count: translated_batch.size - skipped_empty, # Only count non-empty as "translated"
+          skipped_count: skipped_empty
+        }
+      end
+
+      private_class_method :build_translation_options, :save_batch_translations
+    end
+  end
+end

data/lib/fastlane/plugin/translate/helper/translation_error_handler.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module FastlaneCore
+  class UI
+    unless respond_to?(:select)
+      def self.select(message, options)
+        # Fallback implementation for testing
+        puts "#{message} (#{options.join(', ')})"
+        options.first
+      end
+    end
+  end
+end
+
+module Fastlane
+  module Helper
+    class TranslationErrorHandler
+      def self.handle_rate_limit_error(_batch, batch_index, total_batches)
+        options = ['Wait 60s and retry', 'Skip this batch', 'Abort translation', '❌ Quit']
+        choice = UI.select("⚠️ Rate limit exceeded for batch #{batch_index + 1}/#{total_batches}",
+                           options)
+
+        case choice
+        when 'Wait 60s and retry'
+          UI.message('⏳ Waiting 60 seconds...')
+          sleep(60)
+          :retry
+        when 'Skip this batch'
+          UI.important("⏭️ Skipping batch #{batch_index + 1}")
+          :skip
+        when 'Abort translation'
+          UI.user_error!('❌ Translation aborted by user')
+        when '❌ Quit'
+          :quit
+        end
+      end
+
+      def self.handle_translation_error(error, _batch, batch_index, total_batches)
+        UI.error("❌ Translation error for batch #{batch_index + 1}/#{total_batches}: #{error.message}")
+        options = ['Skip this batch', 'Retry batch', 'Abort translation', '❌ Quit']
+        choice = UI.select('Choose action:', options)
+
+        case choice
+        when 'Skip this batch'
+          UI.important("⏭️ Skipping batch #{batch_index + 1}")
+          :skip
+        when 'Retry batch'
+          UI.message("🔄 Retrying batch #{batch_index + 1}")
+          :retry
+        when 'Abort translation'
+          UI.user_error!('❌ Translation aborted by user')
+        when '❌ Quit'
+          :quit
+        end
+      end
+
+      def self.handle_batch_result(action, retry_count, max_retries)
+        case action
+        when :retry
+          return :retry if retry_count < max_retries
+
+          UI.error("❌ Max retries (#{max_retries}) exceeded")
+          :skip
+        when :skip
+          :skip
+        when :quit
+          :quit
+        else
+          :continue
+        end
+      end
+    end
+  end
+end

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

@@ -2,6 +2,6 @@
 
 module Fastlane
   module Translate
-    VERSION = '0.1.0'
+    VERSION = '0.2.0'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fastlane-plugin-translate
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Tijs Teulings
@@ -175,8 +175,10 @@ files:
 - README.md
 - lib/fastlane/plugin/translate.rb
 - lib/fastlane/plugin/translate/actions/translate_with_deepl.rb
+- lib/fastlane/plugin/translate/helper/batch_translation_processor.rb
 - lib/fastlane/plugin/translate/helper/deepl_language_mapper_helper.rb
 - lib/fastlane/plugin/translate/helper/language_registry_helper.rb
+- lib/fastlane/plugin/translate/helper/translation_error_handler.rb
 - lib/fastlane/plugin/translate/helper/translation_progress_helper.rb
 - lib/fastlane/plugin/translate/version.rb
 homepage: https://github.com/tijs/fastlane-plugin-translate