localio 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ab5c7db7901943df5125445d1151851ba8831d9407dca76a43f08f7127499639
-  data.tar.gz: a2ad9aab66aea7dcea8f41b0c7653d7cde6b8e78b3bdb0390fe1e8ae474f67c2
+  metadata.gz: e811c8aa9cf8dabaff74b28dca5476b389c46e27a2dbb5addd87177f28abf566
+  data.tar.gz: 6536d23be9e050ec9d579e6fd0bd35af573eba46536f2d711acaf5d8ee086dc3
 SHA512:
-  metadata.gz: 04d467b401399b5a7810bdbd2fa1d95cb820c0333942ee36a68bd5ec298596229649d4a665c2c35deae8e9fff5ebead2aa941433960b3fb83410be6d9297a4cd
-  data.tar.gz: 7e3a0348a4d4cc70f8aca67fd52e5bba3b0986df6622e7c000beb8fe6690a28c8bec9c500935868eda2d468263fdcedf1e5996b458cc37ddfc88528bea9d5cc7
+  metadata.gz: 2217300fc3ff1610320e23053d97969c93983caf57ecbbc064c5e4018ba4d599b90c71a70ee27bfa5e38ffc3f52bf8c539110c9c55eefdcec4fe8c0960a4d5bd
+  data.tar.gz: 40b1707ad311b028a76a4a0b5f26485153642fc48a89b2e488b7c7b3c13e146f82b55f72bf6a18481082a76b486719c33f1936c83a706d94b14afd7a28b3e230

data/.gitignore

@@ -19,4 +19,5 @@ tmp
 .idea/
 testing/
 .vscode/launch.json
-.worktrees/
+.worktrees/
+vendor/

data/Gemfile.lock

@@ -1,8 +1,8 @@
 PATH
   remote: .
   specs:
-    localio (0.1.8)
-      csv (>= 3.2)
+    localio (0.2.0)
+      csv (~> 3.2)
       google_drive (~> 3.0)
       nokogiri (~> 1.16)
       simple_xlsx_reader (~> 2.0)
@@ -18,29 +18,25 @@ GEM
     csv (3.3.5)
     declarative (0.0.20)
     diff-lcs (1.6.2)
-    faraday (1.10.5)
+    faraday (1.8.0)
       faraday-em_http (~> 1.0)
       faraday-em_synchrony (~> 1.0)
       faraday-excon (~> 1.1)
-      faraday-httpclient (~> 1.0)
-      faraday-multipart (~> 1.0)
+      faraday-httpclient (~> 1.0.1)
       faraday-net_http (~> 1.0)
-      faraday-net_http_persistent (~> 1.0)
+      faraday-net_http_persistent (~> 1.1)
       faraday-patron (~> 1.0)
       faraday-rack (~> 1.0)
-      faraday-retry (~> 1.0)
+      multipart-post (>= 1.2, < 3)
       ruby2_keywords (>= 0.0.4)
     faraday-em_http (1.0.0)
     faraday-em_synchrony (1.0.1)
     faraday-excon (1.1.0)
     faraday-httpclient (1.0.1)
-    faraday-multipart (1.2.0)
-      multipart-post (~> 2.0)
     faraday-net_http (1.0.2)
     faraday-net_http_persistent (1.2.0)
     faraday-patron (1.0.0)
     faraday-rack (1.0.0)
-    faraday-retry (1.0.3)
     google-apis-core (0.11.3)
       addressable (~> 2.5, >= 2.5.1)
       googleauth (>= 0.16.2, < 2.a)
@@ -131,7 +127,7 @@ PLATFORMS
 
 DEPENDENCIES
   localio!
-  rake
+  rake (~> 13.0)
   rspec (~> 3.0)
 
 BUNDLED WITH

data/README.md

@@ -73,6 +73,7 @@ Option                      | Description
 * `:json` for an easy JSON format for localizables. The `output_path` is yours to decide :)
 * `:java_properties` for .properties files used mainly in Java. Files named language_(lang).properties will be generated in `output_path`'s root directory.
 * `:resx` for .resx files used by .NET projects, e.g. Windows Forms, Windows Phone or Xamarin.
+* `: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.
 
 #### Extra platform parameters
 
@@ -103,6 +104,14 @@ platform :resx, :resource_file => "WebResources"
 # ... rest of your Locfile ...
 ````
 
+##### Twine - :twine
+
+By default the output file is named `strings.txt`. Use `:output_file` to override:
+
+````ruby
+platform :twine, :output_file => 'MyApp.strings'
+````
+
 #### Supported sources
 
 ##### Google Drive

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/version.rb

@@ -1,3 +1,3 @@
 module Localio
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end

data/lib/localio/writers/twine_writer.rb

@@ -0,0 +1,48 @@
+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

data/spec/localio/writers/twine_writer_spec.rb

@@ -0,0 +1,68 @@
+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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: localio
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Nacho Lopez
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-02-23 00:00:00.000000000 Z
+date: 2026-02-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -129,6 +129,8 @@ files:
 - bin/localize
 - docs/plans/2026-02-23-modernization-design.md
 - docs/plans/2026-02-23-modernization.md
+- docs/plans/2026-02-23-twine-writer-design.md
+- docs/plans/2026-02-23-twine-writer.md
 - lib/localio.rb
 - lib/localio/config_store.rb
 - lib/localio/filter.rb
@@ -162,6 +164,7 @@ files:
 - lib/localio/writers/rails_writer.rb
 - lib/localio/writers/resx_writer.rb
 - lib/localio/writers/swift_writer.rb
+- lib/localio/writers/twine_writer.rb
 - localio.gemspec
 - spec/fixtures/sample.csv
 - spec/localio/filter_spec.rb
@@ -182,6 +185,7 @@ files:
 - spec/localio/writers/rails_writer_spec.rb
 - spec/localio/writers/resx_writer_spec.rb
 - spec/localio/writers/swift_writer_spec.rb
+- spec/localio/writers/twine_writer_spec.rb
 - spec/localio_spec.rb
 - spec/spec_helper.rb
 - spec/support/shared_terms.rb
@@ -189,7 +193,7 @@ homepage: https://github.com/mrmans0n/localio
 licenses:
 - MIT
 metadata: {}
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -204,8 +208,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.0.3.1
+signing_key: 
 specification_version: 4
 summary: Generates Android, iOS, Rails, JSON, Java Properties, and .NET ResX localization
   files from spreadsheet sources.