localio 0.1.7 → 0.2.1

data/docs/plans/2026-02-23-twine-writer-design.md

@@ -0,0 +1,72 @@
+# Twine Writer Design
+
+**Date:** 2026-02-23
+**Status:** Approved
+
+## Goal
+
+Add a `:twine` platform writer that generates a [Twine](https://github.com/scelis/twine)-compatible `strings.txt` file containing all languages in a single file.
+
+## Output Format
+
+Standard Twine format with tab indentation. All languages are written per key, not per file.
+
+```
+[[section_name]]
+	[key_name]
+		en = English value
+		es = Spanish value
+		comment = Optional comment
+
+	[another_key]
+		en = Another value
+		es = Otro valor
+```
+
+## Term Mapping
+
+| Localio term | Twine output |
+|---|---|
+| `[init-node]` | `[[section_name]]` (value from default language) |
+| `[end-node]` | blank line (sections close implicitly) |
+| `[comment]` | buffered; written as `comment = ...` under the next real key |
+| regular key | `[key]` block with one `lang = value` line per language |
+
+## Architecture
+
+**Approach:** Pure Ruby writer (no ERB template). The comment-buffering logic and single-file-all-languages structure don't fit ERB well.
+
+### Writer class
+
+- **File:** `lib/localio/writers/twine_writer.rb`
+- **Class:** `TwineWriter`
+- **Interface:** `self.write(languages, terms, path, formatter, options)` — matches all existing writers
+
+### Algorithm (single pass)
+
+1. Open output file (`strings.txt` or `options[:output_file]`)
+2. `pending_comment = nil`
+3. For each term:
+   - `[comment]` → store `pending_comment` from default language value
+   - `[init-node]` → write `[[value]]`, reset `pending_comment`
+   - `[end-node]` → write blank line
+   - regular key → write `[key]` block with all lang translations; if `pending_comment` is set, append `\t\tcomment = ...` and clear it
+
+### Platform registration
+
+- Registered in `lib/localio.rb` as `:twine`
+- Locfile usage: `platform :twine` or `platform :twine, :output_file => 'custom.txt'`
+
+### Key formatting
+
+- Smart formatter defaults to snake_case (consistent with android/rails)
+
+## Testing
+
+`spec/localio/writers/twine_writer_spec.rb` using the existing `standard terms` shared context and `Dir.mktmpdir` isolation. Cases:
+
+- Creates `strings.txt` in the output path
+- All languages present in each key block
+- `[init-node]` produces `[[section]]` header
+- `[comment]` row attaches as `comment = ...` to the following key
+- `:output_file` option overrides the default filename

data/docs/plans/2026-02-23-twine-writer.md

@@ -0,0 +1,267 @@
+# Twine Writer Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Add a `:twine` platform writer that generates a single Twine-compatible `strings.txt` containing all languages.
+
+**Architecture:** Pure Ruby writer (no ERB template). Single-pass over terms: buffers `[comment]` rows and attaches them to the next real key, maps `[init-node]`/`[end-node]` to Twine `[[section]]` headers, writes all language translations per key. Registered in `localizable_writer.rb` alongside the existing 7 writers.
+
+**Tech Stack:** Ruby 3.2+, RSpec 3.x, stdlib FileUtils
+
+---
+
+## Task 1: Write the TwineWriter spec (failing)
+
+**Files:**
+- Create: `spec/localio/writers/twine_writer_spec.rb`
+
+**Step 1: Create the spec file**
+
+```ruby
+require 'localio/string_helper'
+require 'localio/term'
+require 'localio/formatter'
+require 'localio/writers/twine_writer'
+
+RSpec.describe TwineWriter do
+  include_context 'standard terms'
+  # standard terms provides: languages {'en'=>1,'es'=>2,'fr'=>3},
+  # default_language 'en', and terms:
+  #   [comment] "Section General", app_name, greeting, dots_test, ampersand_test
+
+  let(:options) { { default_language: 'en' } }
+
+  describe '.write' do
+    it 'creates strings.txt in the output path' do
+      Dir.mktmpdir do |tmpdir|
+        Dir.chdir(tmpdir) { TwineWriter.write(languages, terms, tmpdir, :smart, options) }
+        expect(File).to exist(File.join(tmpdir, 'strings.txt'))
+      end
+    end
+
+    it 'uses a custom filename when :output_file is specified' do
+      Dir.mktmpdir do |tmpdir|
+        Dir.chdir(tmpdir) do
+          TwineWriter.write(languages, terms, tmpdir, :smart, options.merge(output_file: 'translations.txt'))
+        end
+        expect(File).to exist(File.join(tmpdir, 'translations.txt'))
+        expect(File).not_to exist(File.join(tmpdir, 'strings.txt'))
+      end
+    end
+
+    it 'includes all languages for each key' do
+      Dir.mktmpdir do |tmpdir|
+        Dir.chdir(tmpdir) { TwineWriter.write(languages, terms, tmpdir, :smart, options) }
+        content = File.read(File.join(tmpdir, 'strings.txt'))
+        expect(content).to include('en = My App')
+        expect(content).to include('es = Mi Aplicación')
+        expect(content).to include('fr = Mon Application')
+      end
+    end
+
+    it 'writes [init-node] terms as [[section]] headers' do
+      section_terms = [
+        Term.new('[init-node]').tap { |t| t.values['en'] = 'General'; t.values['es'] = 'General'; t.values['fr'] = 'General' },
+        Term.new('app_name').tap   { |t| t.values['en'] = 'My App';   t.values['es'] = 'Mi App';  t.values['fr'] = 'Mon App' },
+        Term.new('[end-node]').tap { |t| t.values['en'] = 'end';      t.values['es'] = 'end';     t.values['fr'] = 'end' },
+      ]
+      Dir.mktmpdir do |tmpdir|
+        Dir.chdir(tmpdir) { TwineWriter.write(languages, section_terms, tmpdir, :smart, options) }
+        content = File.read(File.join(tmpdir, 'strings.txt'))
+        expect(content).to include('[[General]]')
+      end
+    end
+
+    it 'attaches [comment] value as comment = on the following key' do
+      Dir.mktmpdir do |tmpdir|
+        Dir.chdir(tmpdir) { TwineWriter.write(languages, terms, tmpdir, :smart, options) }
+        content = File.read(File.join(tmpdir, 'strings.txt'))
+        # [comment] "Section General" appears before app_name and attaches to it
+        expect(content).to include("\t\tcomment = Section General")
+        # The comment block appears before the greeting key block
+        comment_pos  = content.index('comment = Section General')
+        greeting_pos = content.index('[greeting]')
+        expect(comment_pos).to be < greeting_pos
+      end
+    end
+  end
+end
+```
+
+**Step 2: Run the spec to confirm it fails with "uninitialized constant TwineWriter"**
+
+```bash
+bundle exec rspec spec/localio/writers/twine_writer_spec.rb --format documentation 2>&1
+```
+
+Expected: `LoadError` or `NameError: uninitialized constant TwineWriter`
+
+---
+
+## Task 2: Implement TwineWriter
+
+**Files:**
+- Create: `lib/localio/writers/twine_writer.rb`
+
+**Step 1: Create the writer**
+
+```ruby
+require 'fileutils'
+require 'localio/formatter'
+
+class TwineWriter
+  def self.write(languages, terms, path, formatter, options)
+    puts 'Writing Twine translations...'
+
+    default_language = options[:default_language]
+    output_filename  = options[:output_file] || 'strings.txt'
+
+    FileUtils.mkdir_p(path)
+
+    File.open(File.join(path, output_filename), 'w') do |f|
+      pending_comment = nil
+
+      terms.each do |term|
+        if term.is_comment?
+          pending_comment = term.values[default_language]
+        elsif term.keyword == '[init-node]'
+          f.puts "[[#{term.values[default_language]}]]"
+          pending_comment = nil
+        elsif term.keyword == '[end-node]'
+          f.puts ''
+          pending_comment = nil
+        else
+          key = Formatter.format(term.keyword, formatter, method(:twine_key_formatter))
+          f.puts "\t[#{key}]"
+          languages.keys.each do |lang|
+            f.puts "\t\t#{lang} = #{term.values[lang]}"
+          end
+          if pending_comment
+            f.puts "\t\tcomment = #{pending_comment}"
+            pending_comment = nil
+          end
+          f.puts ''
+        end
+      end
+    end
+
+    puts " > #{output_filename.yellow}"
+  end
+
+  private
+
+  def self.twine_key_formatter(key)
+    key.space_to_underscore.strip_tag.downcase
+  end
+end
+```
+
+**Step 2: Run the spec to confirm all 5 tests pass**
+
+```bash
+bundle exec rspec spec/localio/writers/twine_writer_spec.rb --format documentation 2>&1
+```
+
+Expected: `5 examples, 0 failures`
+
+**Step 3: Run the full suite to confirm no regressions**
+
+```bash
+bundle exec rspec --format progress 2>&1 | tail -5
+```
+
+Expected: `112 examples, 0 failures`
+
+**Step 4: Commit**
+
+```bash
+git add lib/localio/writers/twine_writer.rb spec/localio/writers/twine_writer_spec.rb
+git commit -m "feat: add TwineWriter for Twine-compatible strings.txt output"
+```
+
+---
+
+## Task 3: Register :twine in LocalizableWriter
+
+**Files:**
+- Modify: `lib/localio/localizable_writer.rb`
+
+**Step 1: Add the require and case branch**
+
+At the top of `lib/localio/localizable_writer.rb`, add after the last `require` line:
+
+```ruby
+require 'localio/writers/twine_writer'
+```
+
+In the `case platform` block, add before the `else`:
+
+```ruby
+      when :twine
+        TwineWriter.write languages, terms, path, formatter, options
+```
+
+Also update the error message in the `else` branch to include `:twine`:
+
+```ruby
+        raise ArgumentError, 'Platform not supported! Current possibilities are :android, :ios, :json, :rails, :java_properties, :resx, :twine'
+```
+
+**Step 2: Run the full suite to confirm nothing broke**
+
+```bash
+bundle exec rspec --format progress 2>&1 | tail -5
+```
+
+Expected: `112 examples, 0 failures`
+
+**Step 3: Commit**
+
+```bash
+git add lib/localio/localizable_writer.rb
+git commit -m "feat: register :twine platform in LocalizableWriter"
+```
+
+---
+
+## Task 4: Update README
+
+**Files:**
+- Modify: `README.md`
+
+**Step 1: Add :twine to the supported platforms list**
+
+Find the `#### Supported platforms` section and add after the `:resx` bullet:
+
+```markdown
+* `:twine` for [Twine](https://github.com/scelis/twine)-compatible `strings.txt` files containing all languages in a single file. The `output_path` is the directory where the file will be written.
+```
+
+**Step 2: Add a Twine source section after the ResX platform parameters section**
+
+Find the `#### Supported sources` section header and add a new platform parameters sub-section before it (after the ResX section):
+
+```markdown
+##### Twine - :twine
+
+By default the output file is named `strings.txt`. Use `:output_file` to override:
+
+````ruby
+platform :twine, :output_file => 'MyApp.strings'
+````
+```
+
+**Step 3: Run the full suite one final time**
+
+```bash
+bundle exec rspec --format progress 2>&1 | tail -5
+```
+
+Expected: `112 examples, 0 failures`
+
+**Step 4: Commit**
+
+```bash
+git add README.md
+git commit -m "docs: document :twine platform in README"
+```

data/lib/localio/localizable_writer.rb

@@ -5,6 +5,7 @@ require 'localio/writers/json_writer'
 require 'localio/writers/rails_writer'
 require 'localio/writers/java_properties_writer'
 require 'localio/writers/resx_writer'
+require 'localio/writers/twine_writer'
 
 module LocalizableWriter
   def self.write(platform, languages, terms, path, formatter, options)
@@ -23,8 +24,10 @@ module LocalizableWriter
         JavaPropertiesWriter.write languages, terms, path, formatter, options
       when :resx
         ResXWriter.write languages, terms, path, formatter, options
+      when :twine
+        TwineWriter.write languages, terms, path, formatter, options
       else
-        raise ArgumentError, 'Platform not supported! Current possibilities are :android, :ios, :json, :rails, :java_properties, :resx'
+        raise ArgumentError, 'Platform not supported! Current possibilities are :android, :ios, :json, :rails, :java_properties, :resx, :twine'
     end
   end
 end

data/lib/localio/processors/csv_processor.rb

@@ -42,7 +42,7 @@ class CsvProcessor
         unless platform_options[:avoid_lang_downcase]
           default_language = default_language.downcase
           lang = lang.downcase
-         end
+        end
 
         unless col_text.to_s == ''
           languages.store lang, column

data/lib/localio/processors/google_drive_processor.rb

@@ -1,6 +1,5 @@
 require 'google_drive'
 require 'localio/term'
-require 'localio/config_store'
 
 class GoogleDriveProcessor
 
@@ -19,9 +18,11 @@ class GoogleDriveProcessor
     client_id = options[:client_id]
     client_secret = options[:client_secret]
 
-    # We need client_id / client_secret
-    raise ArgumentError, ':client_id required for Google Drive. Check how to get it here: https://developers.google.com/drive/web/auth/web-server' if client_id.nil?
-    raise ArgumentError, ':client_secret required for Google Drive. Check how to get it here: https://developers.google.com/drive/web/auth/web-server' if client_secret.nil?
+    # We need client_id / client_secret (unless a service-account key is supplied)
+    unless options[:client_token].is_a?(String) && File.file?(options[:client_token].to_s)
+      raise ArgumentError, ':client_id required for Google Drive. Check how to get it here: https://developers.google.com/drive/web/auth/web-server' if client_id.nil?
+      raise ArgumentError, ':client_secret required for Google Drive. Check how to get it here: https://developers.google.com/drive/web/auth/web-server' if client_secret.nil?
+    end
 
     override_default = nil
     override_default = platform_options[:override_default] unless platform_options.nil? or platform_options[:override_default].nil?
@@ -29,50 +30,23 @@ class GoogleDriveProcessor
     # Log in and get spreadsheet
     puts 'Logging in to Google Drive...'
     begin
-      client = Google::APIClient.new application_name: 'Localio', application_version: Localio::VERSION
-      auth = client.authorization
-      auth.client_id = client_id
-      auth.client_secret = client_secret
-      auth.scope =
-          "https://docs.google.com/feeds/" +
-              "https://www.googleapis.com/auth/drive " +
-              "https://spreadsheets.google.com/feeds/"
-      auth.redirect_uri = "urn:ietf:wg:oauth:2.0:oob"
-
-      config = ConfigStore.new
-
-      access_token = nil
-
-      if options.has_key?(:client_token)
-        puts 'Refreshing auth token...'
-        auth.refresh_token = options[:client_token]
-        auth.refresh!
-        access_token = auth.access_token
-      elsif config.has? :refresh_token
-        puts 'Refreshing auth token...'
-        auth.refresh_token = config.get :refresh_token
-        auth.refresh!
-        access_token = auth.access_token
+      session = nil
+
+      # Service-account key file (JSON) path supplied via :client_token
+      if options[:client_token].is_a?(String) && File.file?(options[:client_token].to_s)
+        session = GoogleDrive::Session.from_service_account_key(options[:client_token])
       else
-        puts "1. Open this page in your browser:\n#{auth.authorization_uri}\n\n"
-        puts "2. Enter the authorization code shown in the page: "
-        auth.code = $stdin.gets.chomp
-        auth.fetch_access_token!
-        access_token = auth.access_token
+        # OAuth2 config-file flow (from_config saves/loads the refresh token)
+        config_path = File.join(Dir.home, '.localio_gdrive_config.json')
+        session = GoogleDrive::Session.from_config(
+          config_path,
+          client_id: client_id,
+          client_secret: client_secret
+        )
       end
-
-    if !options.has_key?(:client_token)
-      puts 'Store auth data...'
-      config.store :refresh_token, auth.refresh_token
-      config.store :access_token, auth.access_token
-      config.persist
-    end
-
-      # Creates a session
-      session = GoogleDrive.login_with_oauth(access_token)
     rescue => e
       puts "Error: #{e.inspect}"
-      raise 'Couldn\'t access Google Drive. Check your values for :client_id and :client_secret, and delete :access_token if present (you might need to refresh its value so please remove it)'
+      raise 'Couldn\'t access Google Drive. Check your values for :client_id and :client_secret.'
     end
     puts 'Logged in!'
 
@@ -125,7 +99,7 @@ class GoogleDriveProcessor
         unless platform_options[:avoid_lang_downcase]
           default_language = default_language.downcase
           lang = lang.downcase
-         end
+        end
 
         unless col_text.to_s == ''
           languages.store lang, column

data/lib/localio/processors/xlsx_processor.rb

@@ -49,7 +49,7 @@ class XlsxProcessor
         unless platform_options[:avoid_lang_downcase]
           default_language = default_language.downcase
           lang = lang.downcase
-         end
+        end
 
         unless col_text.to_s == ''
           languages.store lang, column

data/lib/localio/template_handler.rb

@@ -6,11 +6,13 @@ class TemplateHandler
     full_template_path = File.join(File.dirname(File.expand_path(__FILE__)), "templates/#{template_name}")
     input_file = File.open(full_template_path, 'rb')
     template = input_file.read
+   
     input_file.close
     renderer = ERB.new(template)
     output = renderer.result(segments.get_binding)
     output_file = File.new(generated_file_name, 'w')
-    output_file.write(output)
+    output_replace = output.gsub(",}", "}")
+    output_file.write(output_replace)
     output_file.close
 
     destination_path = File.join(target_directory, generated_file_name)

data/lib/localio/templates/android_localizable.erb

@@ -1,11 +1,23 @@
 <!-- Localizable created with localio. DO NOT MODIFY. -->
 <resources>
 <%
+node_keys =[]
 @segments.each do |term|
      if term.is_comment? %>
   <!-- <%= term.translation %> -->
-<% else %>  <string name="<%= term.key %>"><%= term.translation %></string>
-<%   end
+<% else 
+    if term.key == '[init-node]' or term.key == '[end-node]'
+          node_keys << term.translation if term.key == '[init-node]'
+          node_keys.pop if term.key == '[end-node]'
+      else
+        if node_keys.length() > 0
+            key_join = node_keys.join("_")+"_"+term.key
+        else
+            key_join = term.key
+        end
+%>  <string name="<%= key_join %>"><%= term.translation %></string>
+<%    end 
+    end
   end
 %>
 </resources>

data/lib/localio/templates/ios_constant_localizable.erb

@@ -6,6 +6,20 @@ GENERATED - DO NOT MODIFY - use localio instead.
 Created by localio.
 */
 
-<% @segments.each do |term| %>
-#define		<%= term.key %>		NSLocalizedString(@"<%= term.translation %>",nil)<%
+<% 
+node_keys = []
+@segments.each do |term|
+    if term.key == '[init-node]' or term.key == '[end-node]'
+        node_keys << term.translation if term.key == '[init-node]'
+        node_keys.pop if term.key == '[end-node]'
+    else
+        if node_keys.length() >0
+            key_join = node_keys.join("_").capitalize+"_"+term.key.downcase
+        else
+            key_join = term.key
+        end
+%>
+#define		kLocale<%= key_join %>		NSLocalizedString(@"_<%= key_join %>",nil)
+<%
+    end
 end %>

data/lib/localio/templates/ios_localizable.erb

@@ -6,12 +6,27 @@ GENERATED - DO NOT MODIFY - use the localio gem instead.
 Created by localio.
 */
 
-<% @segments.each do |term| %>
-<%
-  if term.is_comment?
+<% 
+  node_keys = []
+  @segments.each do |term| 
+    if term.is_comment?
+%>
+  // <%= term.translation %>
+<% 
+    else 
+      if term.key == '[init-node]' or term.key == '[end-node]'
+          node_keys << term.translation if term.key == '[init-node]'
+          node_keys.pop if term.key == '[end-node]'
+      else
+        if node_keys.length() > 0
+            key_join = node_keys.join("_").capitalize+"_"+term.key.downcase
+        else
+            key_join = term.key
+        end
 %>
-// <%= term.translation %>
-<% else %>"<%= term.key %>" = "<%= term.translation %>";<%
+  "_<%= key_join %>" = "<%= term.translation %>";
+<%
+      end
     end
   end
 %>

data/lib/localio/templates/java_properties_localizable.erb

@@ -1,10 +1,24 @@
 # Localizable created with localio. DO NOT MODIFY.
 #
 # Language: <%= @language %>
-<% @segments.each do |term|
+<%
+node_keys = []
+@segments.each do |term|
 	if term.is_comment? %>
 # <%= term.translation %>
-<% 	else %><%= term.key %>=<%= term.translation %>
+<% 
+else
+    if term.key == '[init-node]' or term.key == '[end-node]'
+        node_keys << term.translation if term.key == '[init-node]'
+        node_keys.pop if term.key == '[end-node]'
+    else
+      if node_keys.length() > 0
+        key_join = node_keys.join("_")+"_"+term.key
+      else
+        key_join = term.key
+      end
+%><%= key_join %>=<%= term.translation %>
 <%  end
   end
+end
 %>

data/lib/localio/templates/json_localizable.erb

@@ -4,12 +4,13 @@
         "language": "<%= @language %>"
     },
     "translations": {
-<%   @segments.each do |term|
+<%   @segments.each.with_index do |term, index|
          term_value = term.translation
          term_key = term.key
-
-         term_key = '___comment___' if term.is_comment?
-%>      "<%= term_key %>": "<%= term_value %>"<% unless term == @segments.last %>,<% end %>
-<%     end %>
+         count_to_string = index.to_s
+         term_key = '___comment_'+count_to_string+'___' if term.is_comment?
+        if term.key == '[init-node]'%>  
+    "<%= term_value %>": {<% elsif term.key == '[end-node]'%>}<% unless term == @segments.last %>,<% end %><% else %>
+    "<%= term_key %>": "<%= term_value %>"<% unless term == @segments.last %>,<% end %><% end end %>
     }
 }

data/lib/localio/templates/rails_localizable.erb

@@ -4,10 +4,22 @@
 
 <%= @language %>:
 <%
+node_keys = []
 @segments.each do |term|
-     if term.is_comment? %>
+    if term.is_comment? %>
 # <%= term.translation %>
-<% else %>  <%= term.key %>: "<%= term.translation %>"
-<%   end
+<% else 
+    if term.key == '[init-node]' or term.key == '[end-node]'
+      node_keys << term.translation if term.key == '[init-node]'
+      node_keys.pop if term.key == '[end-node]'
+    else
+      if node_keys.length() > 0
+        key_join = node_keys.join("_")+"_"+term.key
+      else
+        key_join = term.key
+      end
+%>  <%= key_join %>: "<%= term.translation %>"
+<%  end    
   end
+end
 %>

data/lib/localio/templates/resx_localizable.erb

@@ -122,14 +122,26 @@
     <comment>Controls the Language and ensures that the font for all elements in the RootFrame aligns with the app's language. Set to the language code of this resource file's language.</comment>
   </data>
 <%
+node_keys = []
 @segments.each do |term|
      if term.is_comment? %>
   <!-- <%= term.translation %> -->
-<% else %>  <data name="<%= term.key %>" xml:space="preserve">
+<% else 
+ if term.key == '[init-node]' or term.key == '[end-node]'
+      node_keys << term.translation if term.key == '[init-node]'
+      node_keys.pop if term.key == '[end-node]'
+    else
+      if node_keys.length() > 0
+        key_join = node_keys.join().capitalize+term.key.capitalize
+      else
+        key_join = term.key
+      end
+%>  <data name="<%= key_join %>" xml:space="preserve">
     <value><![CDATA[<%= term.translation %>]]></value>
     <comment/>
   </data>
-<%   end
+<%  end
+   end
   end
 %>