i18nize 0.5.1 → 0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ecaecd54d2f036282dddadfefe26591090c54272cf6a5646fb12d53367509795
-  data.tar.gz: '08adc947c1a7b46f2f7e3dc486d3429bb9e404ed9d7b61ab683a6813ee45cbd2'
+  metadata.gz: ed1bfd2cff604aa20337cfd2e87dd47985ab66d470ee13fa1241378e8c7613d2
+  data.tar.gz: 8e2a54ea7acb3ff57233944f81648f8243f732768278cd77478f7bf5fed08d35
 SHA512:
-  metadata.gz: 0a32cac5c9df881264c7ae1688345410efa5ed64d8a3481526f83d2f4ef84f888af4e83fdce0af2da09f9f2594918d2606ffe31bd3c66e4a7af84f823c2443eb
-  data.tar.gz: 68fa3a1028e87cf9965e20be6ab5b663c438b0b27ec3269fc8fc7a4543a59551f832d206e416cf79784e38cca474be09aa9ddc47d208bd581cf0aa830f0d4ce5
+  metadata.gz: f7322c2b6b1bc505090789774f340404186be3dcaed272629b19ab914bd36af3f8c1d50cde289ce29e203c60fc3273d5a8981c11060fdbfd571d261bc96803a3
+  data.tar.gz: ff89ec4d79479de9c40855916fc0a5dfa3f87a6e300459625edcfb7928aafb54ac15faec21e3a9e68d6a8c47543d716ac53a41620496363e86c7abb5314d00e4

data/CHANGELOG.md

@@ -1,15 +1,19 @@
 # Changelog
 
-## [Unreleased]
-
----
-
+## [0.6] - 2025-09-11
 ### Added
-### Changed
-### Removed
-### Fixed
+- CLI flag `--only_blank`: fills only missing or blank keys with a placeholder  
+  (`<locale>.<full.key> missing`) instead of translating with DeepL.
+- Environment variable `I18NIZE_ALLOW_EMPTY=1`: skips keys where the source value is empty  
+  or whitespace-only, preventing them from being copied/translated.
 
----
+### Changed
+- CLI parsing improved: `--from` can now be used **before or after** the target locale.  
+  Examples:  
+  ```bash
+  i18nize cs --from de
+  i18nize --from de cs
+````
 
 ---
 

data/README.md

@@ -1,5 +1,9 @@
+
 # i18nize
 
+[![CI](https://github.com/nikolas2145/i18nize/actions/workflows/main.yml/badge.svg)](https://github.com/nikolas2145/i18nize/actions/workflows/main.yml)
+[![Gem Version](https://badge.fury.io/rb/i18nize.svg)](https://badge.fury.io/rb/i18nize)
+
 🧠 Automatically fills in missing I18n YAML keys using DeepL translation API.
 Designed to streamline multi-language support in Ruby and Rails projects.
 
@@ -8,6 +12,7 @@ Designed to streamline multi-language support in Ruby and Rails projects.
 * Detects missing or empty translation keys in locale files
 * Supports multiple YAML files and nested directories (e.g. `config/locales/api/en.yml`)
 * Automatically translates from a source locale (**default: `en`**) to a target (e.g. `cs`)
+* **Placeholder mode** to fill only blank/missing keys without DeepL (`--only_blank`)
 * Integrates with DeepL API (Free or Pro)
 * Safely merges translations into corresponding `*.yml` files
 * Handles structural conflicts by overwriting target with source truth
@@ -20,7 +25,7 @@ Add this line to your application's Gemfile:
 
 ```ruby
 gem "i18nize"
-```
+````
 
 Then run:
 
@@ -76,6 +81,31 @@ i18nize cs --missing de
 
 This mode only lists missing keys, no translations are written.
 
+### 4. Fill placeholders for blank/missing keys (no DeepL)
+
+```bash
+# Insert placeholders instead of translating
+i18nize cs --only_blank
+```
+
+This scans all keys in the **source** locale (default `en`) and, for any **missing or blank** value in the target locale, inserts a placeholder:
+
+```
+<locale>.<full.dot.key> missing
+```
+
+Example:
+
+```yaml
+en:
+  test:
+    title: "Testing"
+cs:
+  test:
+    title: "cs.test.title missing"
+```
+
+Existing non-blank values in the target are left untouched.
 
 ## 🛡️ Character limit check
 
@@ -132,8 +162,11 @@ For now, configuration is via CLI flags and environment variables:
 
 * `--from LANG` (default `en`)
 * `--missing [FROM]` (list missing keys only)
-* `DEEPL_API_KEY` (required)
+* `--only_blank` (fill only blank/missing keys with placeholders, no DeepL)
+* `DEEPL_API_KEY` (required for translation mode)
 * `DEEPL_ENDPOINT` (optional, only for Pro)
+* `I18NIZE_ALLOW_EMPTY == "1"` → **skip empty/whitespace-only values** in the source when inserting or translating
+  (i.e., if a source value is `""` or `" "` it will be ignored and not propagated to the target)
 
 ---
 
@@ -142,5 +175,5 @@ For now, configuration is via CLI flags and environment variables:
 * RSpec test suite
 * YAML key sorting / format preservation
 * Richer conflict resolution strategies (configurable overwrite / skip)
-* Use custom char limit 
+* Use custom char limit
 

data/lib/i18nize/cli.rb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
 require "optparse"
-
 require "i18nize/translator"
 require "i18nize/inserter"
 require "i18nize/comparer"
 
 module I18nize
+  # CLI for i18nize
   class CLI
     def self.run(argv)
       new(argv).run
@@ -16,107 +16,102 @@ module I18nize
       @argv = argv.dup
       @options = {
         from: "en",
-        mode: :translate,
+        mode: :translate, # :translate | :missing | :only_blank
         missing_from: nil
       }
     end
 
     def run
-      print_help_and_exit if @argv.empty? || help_requested?
-
-      first = @argv.first
-      parse_flags!(@argv[1..] || [])
-
-      to_locale = parse_positional_locale!(first)
+      remaining = parse_flags!(@argv)
+      abort usage unless remaining.any?
+      to_locale = remaining.shift.strip
 
-      if @options[:mode] == :missing
+      case @options[:mode]
+      when :missing
         from = @options[:missing_from] || @options[:from]
         show_missing_translations(from:, to: to_locale)
-        return 0
+      when :only_blank
+        run_only_blank(to_locale)
+      else
+        run_translation(to_locale)
       end
-
-      run_translation(to_locale)
       0
     rescue OptionParser::InvalidOption => e
       warn red(e.message)
-      print_help_and_exit(2)
+      puts usage
+      2
     rescue SystemExit => e
       raise e
     rescue => e
       warn red("Error: #{e.class}: #{e.message}")
       e.backtrace.each { |l| warn l } if ENV["I18NIZE_DEBUG"] == "1"
-      exit 1
+      1
     end
 
     private
 
-    def help_requested?
-      (@argv & %w[-h --help help]).any?
-    end
-
-    def parse_positional_locale!(arg)
-      abort yellow("Usage: i18nize <to_locale> [--from en] [--missing [FROM]]") unless arg
-      arg.strip
-    end
-
-    def parse_flags!(rest)
-      OptionParser.new do |o|
+    def parse_flags!(args)
+      parser = OptionParser.new do |o|
         o.banner = "Usage: i18nize <to_locale> [options]"
-        o.on("--from LANG", "Source language for comparison/translation (default: en)") { |v| @options[:from] = v }
-
+        o.on("--from LANG", "Source language (default: en)") { |v| @options[:from] = v }
         o.on("--missing", "--missing [FROM]", "List missing keys only; optionally specify source locale") do |from|
           @options[:mode] = :missing
           @options[:missing_from] = from if from && !from.strip.empty?
         end
+        o.on("--only_blank", "Fill only missing/blank keys with '<locale>.<full.key> missing'") do
+          @options[:mode] = :only_blank
+        end
+        o.on("-h", "--help", "Show help") { puts usage; exit 0 }
+      end
 
-        o.on("-h", "--help", "Show help") { print_help_and_exit }
-      end.parse!(rest)
+      parser.parse!(args)
+      args
     end
 
     def show_missing_translations(from:, to:)
       load_rails_if_available
       puts cyan("🔍 Missing keys for #{to} (from #{from})")
-
       missing = I18nize::Comparer.missing_translations(from_locale: from, to_locale: to)
-
       if missing.empty?
         puts green("✅ No missing translations.")
         return
       end
-
-      total_keys = missing.total_keys
-      puts yellow("⚠️  #{total_keys} missing #{total_keys == 1 ? 'key' : 'keys'}:")
-
+      total = missing.total_keys
+      puts yellow("⚠️  #{total} missing #{total == 1 ? 'key' : 'keys'}:")
       missing.values_by_file.each do |file, keys_hash|
         puts "  #{file}:"
-        keys_hash.keys.sort.each do |k|
-          puts "    - #{k.sub(/^#{from}\./, '')}"
-        end
+        keys_hash.keys.sort.each { |k| puts "    - #{k.sub(/^#{Regexp.escape(from)}\./, "")}" }
       end
     end
 
-    def run_translation(to_locale)
+    def run_only_blank(to_locale)
       load_env_files
+      load_rails_if_available
+      puts cyan("Filling only blank/missing keys: from #{@options[:from]} → #{to_locale}")
+      I18nize::Inserter.insert_only_blank(
+        from_locale: @options[:from],
+        to_locale: to_locale
+      )
+      puts green("✅ Placeholders inserted for blank/missing keys.")
+    end
 
+    def run_translation(to_locale)
+      load_env_files
       api_key = ENV["DEEPL_API_KEY"]
       abort red("Missing DEEPL_API_KEY env variable") if api_key.to_s.strip.empty?
-
       load_rails_if_available
 
       puts cyan("Starting translation: from #{@options[:from]} → #{to_locale}")
-
       translator = I18nize::Translator.new(
         auth_key: api_key,
         from_lang: @options[:from].upcase,
         to_lang: to_locale.upcase
       )
-
       I18nize::Inserter.insert_missing(
         from_locale: @options[:from],
         to_locale: to_locale,
         translator: translator
       )
-
       puts green("✅ Translation completed.")
     end
 
@@ -124,18 +119,37 @@ module I18nize
       begin
         require "dotenv/load"
       rescue LoadError
-        # Ignore
       end
     end
 
     def load_rails_if_available
       return if defined?(Rails)
 
-      if File.exist?("config/environment.rb")
-        require_relative "../../config/environment"
-      end
+      require_relative "../../config/environment" if File.exist?("config/environment.rb")
+
     rescue LoadError
-      # Ignore
+      # Ignored
+    end
+
+    def usage
+      <<~HELP
+        Usage:
+          i18nize <to_locale> [options]
+
+        Examples:
+          i18nize cs                    # translate missing from en -> cs
+          i18nize cs --from de          # translate missing from de -> cs
+          i18nize --from de cs          # flags can be before or after the locale
+          i18nize cs --missing          # list missing keys for cs (from en)
+          i18nize cs --missing de       # list missing keys for cs (from de)
+          i18nize cs --only_blank       # fill only blank/missing keys with placeholders
+
+        Options:
+          --from LANG                   Source language (default: en)
+          --missing [FROM]              Only list missing keys (optional override of source)
+          --only_blank                  Insert '<locale>.<full.key> missing' for blank/missing keys
+          -h, --help                    Show this help
+      HELP
     end
 
     def color(text, code) = "\e[#{code}m#{text}\e[0m"
@@ -147,24 +161,5 @@ module I18nize
     def yellow(text) = color(text, 33)
 
     def cyan(text) = color(text, 36)
-
-    def print_help_and_exit(code = 0)
-      puts <<~HELP
-        Usage:
-          i18nize <to_locale> [options]
-
-        Examples:
-          i18nize cs                  # translate missing from en -> cs
-          i18nize cs --from de        # translate missing from de -> cs
-          i18nize cs --missing        # list missing keys for cs (from en)
-          i18nize cs --missing de     # list missing keys for cs (from de)
-
-        Options:
-          --from LANG                 Source language (default: en)
-          --missing [FROM]            Only list missing keys (optional override of source)
-          -h, --help                  Show this help
-      HELP
-      exit code
-    end
   end
 end

data/lib/i18nize/comparer.rb

@@ -4,8 +4,9 @@ require_relative "loader"
 require_relative "missing_set"
 
 module I18nize
+  # Small utility to compare translations from one locale to another
   class Comparer
-    def self.missing_translations(from_locale: "en", to_locale:)
+    def self.missing_translations(to_locale:, from_locale: "en") # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
       from_data = Loader.load_per_file(locale: from_locale)
       to_data   = Loader.load_per_file(locale: to_locale)
 
@@ -37,7 +38,7 @@ module I18nize
       MissingSet.new(from_locale: from_locale, to_locale: to_locale, data: result)
     end
 
-    def self.missing_keys(from_locale: "en", to_locale:)
+    def self.missing_keys(to_locale:, from_locale: "en")
       missing_translations(from_locale: from_locale, to_locale: to_locale).keys_by_file
     end
   end

data/lib/i18nize/inserter.rb

@@ -2,13 +2,15 @@
 
 require "yaml"
 require "fileutils"
+require "byebug"
 require_relative "comparer"
+require_relative "loader"
 
 module I18nize
   class Inserter
     CONFLICT_POLICY = :overwrite # :overwrite | :skip
 
-    def self.insert_missing(from_locale: "en", to_locale:, base_path: "config/locales", translator: nil)
+    def self.insert_missing(to_locale:, from_locale: "en", base_path: "config/locales", translator: nil)
       missing_data = Comparer.missing_translations(from_locale: from_locale, to_locale: to_locale)
 
       if translator
@@ -26,7 +28,7 @@ module I18nize
       overwrites = []
 
       missing_data.data.each do |from_rel_path, translations|
-        dirname  = File.dirname(from_rel_path)
+        dirname = File.dirname(from_rel_path)
         filename = File.basename(from_rel_path)
 
         locale_re = /(^|[._])#{Regexp.escape(from_locale)}\.(ya?ml)$/
@@ -40,7 +42,7 @@ module I18nize
         translation_map =
           if translator
             src_values = translations.values
-            translated_values = translator.translate_texts(src_values) # => pole!
+            translated_values = translator.translate_texts(src_values) # returns array
             translations.keys.zip(translated_values).to_h
           else
             translations
@@ -57,15 +59,70 @@ module I18nize
         puts "\e[32m[i18nize] Inserted #{translation_map.size} keys into #{to_full_path}\e[0m"
       end
 
-      if overwrites.any?
+      return unless overwrites.any?
         puts "\n\e[33m[i18nize] Overwrote #{overwrites.size} scalar node(s) to create nested structure:\e[0m"
         overwrites.each do |c|
           puts "  \e[33m- #{c[:file]}: #{c[:locale]}.#{c[:path].join('.')}\e[0m (was: #{c[:existing_class]})"
         end
+
+    end
+
+    # NEW: fill only missing/blank values with "<locale>.<full.key> missing"
+    def self.insert_only_blank(to_locale:, from_locale: "en", base_path: "config/locales")
+      from_data = Loader.load_per_file(locale: from_locale, base_path: base_path)
+      # to_data = Loader.load_per_file(locale: to_locale, base_path: base_path)
+
+      updated_files = 0
+      overwrites = []
+
+      from_data.each do |from_rel_path, from_keys|
+        dirname = File.dirname(from_rel_path)
+        filename = File.basename(from_rel_path)
+        locale_re = /(^|[._])#{Regexp.escape(from_locale)}\.(ya?ml)$/
+        new_filename = filename.sub(locale_re) { "#{Regexp.last_match(1)}#{to_locale}.#{Regexp.last_match(2)}" }
+        to_rel_path = dirname == "." || dirname.empty? ? new_filename : File.join(dirname, new_filename)
+        to_full_path = File.join(base_path, to_rel_path)
+
+        existing = File.exist?(to_full_path) ? YAML.load_file(to_full_path) : {}
+        existing[to_locale] ||= {}
+
+        changes = 0
+
+        from_keys.each_key do |from_full_key|
+          to_full_key = from_full_key.sub(/^#{Regexp.escape(from_locale)}\./, "#{to_locale}.")
+          path = to_full_key.sub(/^#{Regexp.escape(to_locale)}\./, "").split(".")
+          current = dig_nested(existing[to_locale], path)
+          next if current.to_s.strip.empty? && ENV["I18NIZE_ALLOW_EMPTY"] == "1"
+          next unless current.nil? || current.to_s.strip.empty?
+
+          placeholder = "#{to_full_key} missing"
+          insert_nested(existing[to_locale], path, placeholder, overwrites, to_rel_path, to_locale, :overwrite)
+          changes += 1
+        end
+
+        next unless changes.positive?
+
+        FileUtils.mkdir_p(File.dirname(to_full_path))
+        File.write(to_full_path, existing.to_yaml(line_width: -1))
+        updated_files += 1
+        puts "\e[32m[i18nize] Inserted #{changes} placeholder#{changes == 1 ? '' : 's'} into #{to_full_path}\e[0m"
+      end
+
+      puts "\e[90m[i18nize] No blank or missing keys found.\e[0m" if updated_files.zero?
+
+      return unless overwrites.any?
+
+      puts "\n\e[33m[i18nize] Overwrote #{overwrites.size} scalar node(s) while creating nested structure:\e[0m"
+      overwrites.each do |c|
+        puts "  \e[33m- #{c[:file]}: #{c[:locale]}.#{c[:path].join('.')}\e[0m (was: #{c[:existing_class]})"
       end
     end
 
-    # conflict_policy: :overwrite (replace scalar with {}), :skip (leave as is)
+    def self.dig_nested(hash, path)
+      path.reduce(hash) { |h, k| h.is_a?(Hash) ? h[k] : nil }
+    end
+
+    # conflict_policy: :overwrite (replace scalar with {}), :skip
     def self.insert_nested(base, keys, value, overwrites, file, locale, conflict_policy)
       key = keys.shift
 
@@ -79,18 +136,15 @@ module I18nize
       case cur
       when nil
         base[key] = {}
-        insert_nested(base[key], keys, value, overwrites, file, locale, conflict_policy)
+        return insert_nested(base[key], keys, value, overwrites, file, locale, conflict_policy)
       when Hash
-        insert_nested(cur, keys, value, overwrites, file, locale, conflict_policy)
+        return insert_nested(cur, keys, value, overwrites, file, locale, conflict_policy)
       else
-        if conflict_policy == :overwrite
+        return false unless conflict_policy == :overwrite
           overwrites << { file: file, locale: locale, path: [key, *keys], existing_class: cur.class.to_s }
           base[key] = {}
-          insert_nested(base[key], keys, value, overwrites, file, locale, conflict_policy)
-        else
-          # :skip
-          false
-        end
+        return insert_nested(base[key], keys, value, overwrites, file, locale, conflict_policy)
+
       end
     end
   end

data/lib/i18nize/loader.rb

@@ -3,6 +3,7 @@
 require "yaml"
 
 module I18nize
+  # Loader for i18nize
   class Loader
     def self.load_per_file(locale: "en", base_path: "config/locales")
       files = Dir.glob(File.join(base_path, "**", "*.yml")).select do |f|

data/lib/i18nize/missing_set.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module I18nize
-  require "byebug"
+  # Set of missing translations
   class MissingSet
     attr_reader :from_locale, :to_locale, :data
 

data/lib/i18nize/translator.rb

@@ -4,14 +4,15 @@ require "uri"
 require "json"
 
 module I18nize
+  # Translator for i18nize
   class Translator
     ENDPOINT = ENV.fetch("DEEPL_ENDPOINT", "https://api-free.deepl.com/v2/translate")
     PLACEHOLDER_RE = /%{\s*[^}]+\s*}/
 
     def initialize(auth_key:, from_lang: "EN", to_lang:)
-      @auth_key  = auth_key
+      @auth_key = auth_key
       @from_lang = from_lang
-      @to_lang   = to_lang
+      @to_lang = to_lang
     end
 
     def translate_texts(texts)
@@ -30,7 +31,7 @@ module I18nize
       body_params = [
         ["auth_key", @auth_key],
         ["source_lang", @from_lang],
-        ["target_lang", @to_lang],
+        ["target_lang", @to_lang]
       ] + protected.map { |text| ["text", text] }
 
       req = Net::HTTP::Post.new(uri)
@@ -43,7 +44,7 @@ module I18nize
       json = JSON.parse(res.body)
       out = json["translations"].map { |t| t["text"] }
 
-      out.map { |s| s.gsub(/__I18NIZE_PLH_(\d+)__/) { placeholders[$1.to_i] } }
+      out.map { |s| s.gsub(/__I18NIZE_PLH_(\d+)__/) { placeholders[::Regexp.last_match(1).to_i] } }
     end
   end
 end

data/lib/i18nize/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module I18nize
-  VERSION = "0.5.1"
+  VERSION = "0.6"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: i18nize
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: '0.6'
 platform: ruby
 authors:
 - nikolas2145
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-09-09 00:00:00.000000000 Z
+date: 2025-09-11 00:00:00.000000000 Z
 dependencies: []
 description: "i18nize helps Ruby and Rails projects stay multilingual by automatically
   filling in \nmissing translations in I18n YAML locale files. It scans for missing