localio 0.1.6 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 7545745288cd1d2a90ab07b92aabeba59481e21b
-  data.tar.gz: fa6c825a442d45737232b8095c6d952040456c3f
+SHA256:
+  metadata.gz: ab5c7db7901943df5125445d1151851ba8831d9407dca76a43f08f7127499639
+  data.tar.gz: a2ad9aab66aea7dcea8f41b0c7653d7cde6b8e78b3bdb0390fe1e8ae474f67c2
 SHA512:
-  metadata.gz: 36f73ead59451a89bd13b31a677fb5ff92ce410f1379f8c315abb0be6aaa1d8754b98573f27a02aba0915bfb578f580eaa95e60574789a27e36778604b247d3a
-  data.tar.gz: bb797d0d11972c9b269443b03bfee43d683e60ffbe78abb68218f2b8c816d73c7028962cc8cbdf9d243ab3affda172c6468cbd881c5af5f004faae4ce4a51e2a
+  metadata.gz: 04d467b401399b5a7810bdbd2fa1d95cb820c0333942ee36a68bd5ec298596229649d4a665c2c35deae8e9fff5ebead2aa941433960b3fb83410be6d9297a4cd
+  data.tar.gz: 7e3a0348a4d4cc70f8aca67fd52e5bba3b0986df6622e7c000beb8fe6690a28c8bec9c500935868eda2d468263fdcedf1e5996b458cc37ddfc88528bea9d5cc7

data/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  test:
+    name: Ruby ${{ matrix.ruby }}
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ["3.2", "3.3"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - name: Run tests
+        run: bundle exec rspec

data/.gitignore

@@ -17,4 +17,6 @@ test/tmp
 test/version_tmp
 tmp
 .idea/
-testing/
+testing/
+.vscode/launch.json
+.worktrees/

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--format documentation
+--color

data/.ruby-version

@@ -0,0 +1 @@
+3.3.10

data/Gemfile.lock

@@ -0,0 +1,138 @@
+PATH
+  remote: .
+  specs:
+    localio (0.1.8)
+      csv (>= 3.2)
+      google_drive (~> 3.0)
+      nokogiri (~> 1.16)
+      simple_xlsx_reader (~> 2.0)
+      spreadsheet (~> 1.3)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.8)
+      public_suffix (>= 2.0.2, < 8.0)
+    base64 (0.3.0)
+    bigdecimal (4.0.1)
+    csv (3.3.5)
+    declarative (0.0.20)
+    diff-lcs (1.6.2)
+    faraday (1.10.5)
+      faraday-em_http (~> 1.0)
+      faraday-em_synchrony (~> 1.0)
+      faraday-excon (~> 1.1)
+      faraday-httpclient (~> 1.0)
+      faraday-multipart (~> 1.0)
+      faraday-net_http (~> 1.0)
+      faraday-net_http_persistent (~> 1.0)
+      faraday-patron (~> 1.0)
+      faraday-rack (~> 1.0)
+      faraday-retry (~> 1.0)
+      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)
+      httpclient (>= 2.8.1, < 3.a)
+      mini_mime (~> 1.0)
+      representable (~> 3.0)
+      retriable (>= 2.0, < 4.a)
+      rexml
+    google-apis-drive_v3 (0.46.0)
+      google-apis-core (>= 0.11.0, < 2.a)
+    google-apis-sheets_v4 (0.26.0)
+      google-apis-core (>= 0.11.0, < 2.a)
+    google_drive (3.0.7)
+      google-apis-drive_v3 (>= 0.5.0, < 1.0.0)
+      google-apis-sheets_v4 (>= 0.4.0, < 1.0.0)
+      googleauth (>= 0.5.0, < 1.0.0)
+      nokogiri (>= 1.5.3, < 2.0.0)
+    googleauth (0.17.1)
+      faraday (>= 0.17.3, < 2.0)
+      jwt (>= 1.4, < 3.0)
+      memoist (~> 0.16)
+      multi_json (~> 1.11)
+      os (>= 0.9, < 2.0)
+      signet (~> 0.15)
+    httpclient (2.9.0)
+      mutex_m
+    jwt (2.10.2)
+      base64
+    logger (1.7.0)
+    memoist (0.16.2)
+    mini_mime (1.1.5)
+    mini_portile2 (2.8.9)
+    multi_json (1.19.1)
+    multipart-post (2.4.1)
+    mutex_m (0.3.0)
+    nokogiri (1.19.1)
+      mini_portile2 (~> 2.8.2)
+      racc (~> 1.4)
+    nokogiri (1.19.1-arm64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.19.1-x86_64-linux-gnu)
+      racc (~> 1.4)
+    os (1.1.4)
+    public_suffix (7.0.2)
+    racc (1.8.1)
+    rake (13.3.1)
+    representable (3.2.0)
+      declarative (< 0.1.0)
+      trailblazer-option (>= 0.1.1, < 0.2.0)
+      uber (< 0.2.0)
+    retriable (3.2.1)
+    rexml (3.4.4)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.7)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    ruby-ole (1.2.13.1)
+    ruby2_keywords (0.0.5)
+    rubyzip (3.2.2)
+    signet (0.21.0)
+      addressable (~> 2.8)
+      faraday (>= 0.17.5, < 3.a)
+      jwt (>= 1.5, < 4.0)
+      multi_json (~> 1.10)
+    simple_xlsx_reader (2.0.1)
+      nokogiri
+      rubyzip
+    spreadsheet (1.3.4)
+      bigdecimal
+      logger
+      ruby-ole
+    trailblazer-option (0.1.2)
+    uber (0.1.0)
+
+PLATFORMS
+  arm64-darwin
+  ruby
+  x86_64-linux
+
+DEPENDENCIES
+  localio!
+  rake
+  rspec (~> 3.0)
+
+BUNDLED WITH
+   2.5.22

data/README.md

@@ -51,7 +51,7 @@ source :xlsx,
        :path => 'my_translations.xlsx'
 ````
 
-This would connect localio to your Google Drive and process the spreadsheet with title "[Localizables] My Project!".
+This would read from `my_translations.xlsx` and write iOS localizable files to `my_output_path/`.
 
 The list of possible commands is this.
 
@@ -76,6 +76,11 @@ Option                      | Description
 
 #### Extra platform parameters
 
+
+#####  `avoid_lang_downcase`
+
+By default, language codes are downcased. We can set `:avoid_lang_downcase => true` to avoid this behavior.
+
 ##### iOS - :ios, :swift
 
 We can opt-out from the constants/macros. We will simple need to add `:create_constants => false`. By default, if omitted, the constants will be always created. It's a good practice to have a compile-time check of the existence of your keys; but if you don't like it it's fine.
@@ -104,57 +109,51 @@ platform :resx, :resource_file => "WebResources"
 
 `source :google_drive` will get the translation strings from Google Drive.
 
-You will have to provide some required parameters too. Here is a list of all the parameters.
+Two authentication methods are supported: **OAuth2** (for personal accounts) and **service accounts** (for automated/CI use).
 
 Option                      | Description
 ----------------------------|-------------------------------------------------------------------------
 `:spreadsheet`              | (Req.) Title of the spreadsheet you want to use. Can be a partial match.
-`:login`                    | **DEPRECATED** This is deprecated starting version 0.1.0. Please remove it.
-`:password`                 | **DEPRECATED** This is deprecated starting version 0.1.0. Please remove it.
-`:client_id`                | (Req.) Your Google CLIENT ID.
-`:client_secret`            | (Req.) Your Google CLIENT SECRET.
-
-Please take into account that from version 0.1.0 of Localio onwards we are using **Google OAuth2 authentication**, as the previous one with login/password has been deprecated by Google and cannot be access anymore starting April 20th 2015.
+`:sheet`                    | (Req.) Index number (starting with 0) or name of the sheet w/ the data
+`:client_id`                | Your Google OAuth2 Client ID. Required unless using `:client_token`.
+`:client_secret`            | Your Google OAuth2 Client Secret. Required unless using `:client_token`.
+`:client_token`             | Path to a service account JSON key file. Alternative to OAuth2.
 
-Setting it up is a bit of a pain, although it is only required the first time and can be shared by all your projects:
+###### Option A: OAuth2 (personal account)
 
-1. You have to create a new project in Google Developers Console for using Drive API. You can do that [here](https://console.developers.google.com/flows/enableapi?apiid=drive).
-2. After it is created you will be redirected to the credentials section (if not, just select under APIs and authentication in the sidebar the Credentials section), where you will click in the button labeled **Create new client ID**.
-3. Select the third option, the one that says something like **Installed Application**.
-4. Fill the form with whatever you want. For example, you could put Localio as the product name (the only thing required there).
-5. Select again the third option, **Installed Application**, and in the platform selector select the last one, **Others**.
-6. You will have all the necessary information in the next screen: Client ID and Client Secret.
+1. Go to the [Google Cloud Console](https://console.cloud.google.com/), create a project and enable the **Google Drive API**.
+2. Under **APIs & Services → Credentials**, create an **OAuth client ID**. Choose **Desktop app** as the application type.
+3. Download or copy your **Client ID** and **Client Secret**.
 
-After doing all this, you are ready to add `:client_id` and `:client_secret` fields to your Locfile `source`. It will look somewhat like this at this stage:
+Add them to your Locfile:
 
 ```ruby
 source :google_drive,
        :spreadsheet => '[Localizables] My Project',
-       :client_id => 'XXXXXXXXX-XXXXXXXX.apps.googleusercontent.com',
-       :client_secret => 'asdFFGGhjKlzxcvbnm'
+       :client_id => ENV['GOOGLE_CLIENT_ID'],
+       :client_secret => ENV['GOOGLE_CLIENT_SECRET']
 ```
 
-Then, the first time you run it, you will be prompted to follow some instructions. You will be asked to open a website, where you will be prompted for permission to use the Drive API. After you allow it, you will be given an authorization code, which you will have to paste in your terminal screen when prompted.
+The first time you run `localize`, you will be prompted to open a URL in your browser, grant access to your Drive, and paste the authorization code back into the terminal. After that, the refresh token is saved to `~/.localio_gdrive_config.json` and subsequent runs authenticate automatically.
 
-**NOTE** A hidden file, called .localio.yml, will be created in your Locfile directory. You should **add that file to your ignored resources** in your repository, aka the **.gitignore** file.
+**NOTE** As it is a very bad practice to put your sensitive information in a plain file, it is **strongly recommended** to use environment variables. Export them from your shell profile (`.zshrc`, `.bashrc`, etc.):
 
-**NOTE** As it is a very bad practice to put your sensitive information in a plain file, specially when you would want to upload your project to some repository, it is **VERY RECOMMENDED** that you use environment variables in here. Ruby syntax is accepted so you can use `ENV['CLIENT_SECRET']` and `ENV['CLIENT_ID']` in here.
-
-For example, this.
+```bash
+export GOOGLE_CLIENT_ID="your_client_id"
+export GOOGLE_CLIENT_SECRET="your_client_secret"
+```
 
-````ruby
-source :google_drive,
-       :spreadsheet => '[Localizables] My Project!',
-       :client_id => ENV['CLIENT_ID'],
-       :client_secret => ENV['CLIENT_SECRET']
-````
+###### Option B: Service account (automated/CI use)
 
-And in your .bashrc (or .bash_profile, .zshrc or whatever), you could export those environment variables like this:
+1. In the [Google Cloud Console](https://console.cloud.google.com/), create a **Service Account** under **APIs & Services → Credentials**.
+2. Download the JSON key file.
+3. Share the target spreadsheet with the service account's email address (found in the JSON file under `client_email`).
 
-````ruby
-export CLIENT_ID="your_client_id"
-export CLIENT_SECRET="your_client_secret"
-````
+```ruby
+source :google_drive,
+       :spreadsheet => '[Localizables] My Project',
+       :client_token => 'path/to/service_account_key.json'
+```
 
 ##### XLS
 
@@ -180,7 +179,7 @@ You may specify a `sheet` parameter, otherwise the first sheet will be used.
 Option                      | Description
 ----------------------------|-------------------------------------------------------------------------
 `:path`                     | (Req.) Path for your XLSX file.
-`:sheet`                    | (Optional) Index number (starting with 0) or name of the sheet w/ the data
+`:sheet`                    | (Req.) Index number (starting with 0) or name of the sheet w/ the data
 
 ````ruby
 source :xlsx,

data/bin/localize

@@ -1,11 +1,14 @@
 #!/usr/bin/env ruby
-# encoding: UTF-8
-
+require 'optparse'
 require 'localio'
 
-begin
-  Localio.from_cmdline(ARGV)
-rescue => e
-  abort e.message
-end
+OptionParser.new do |opts|
+  opts.banner = 'Usage: localize [Locfile]'
+  opts.on('-v', '--version', 'Show version') do
+    require 'localio/version'
+    puts Localio::VERSION
+    exit
+  end
+end.parse!
 
+Localio.from_cmdline(ARGV)

data/docs/plans/2026-02-23-modernization-design.md

@@ -0,0 +1,91 @@
+# Localio Modernization Design
+
+**Date:** 2026-02-23
+**Approach:** Option A — tests first, then dependency updates
+
+## Overview
+
+Modernize the Localio gem in two phases:
+
+1. Write a comprehensive RSpec test suite with fixtures and mocks
+2. Update all dependencies to current versions and target Ruby 3.x, using the test suite as a safety net
+
+## Phase 1: Test Suite
+
+### Structure
+
+```
+spec/
+  spec_helper.rb
+  fixtures/
+    sample.csv          # canonical test data: keys in 3 languages, special chars, comments, multi-level keys
+    sample.xlsx         # small binary fixture
+    sample.xls          # small binary fixture
+  localio/
+    term_spec.rb
+    segment_spec.rb
+    filter_spec.rb
+    formatter_spec.rb
+    template_handler_spec.rb
+    processors/
+      csv_processor_spec.rb
+      xlsx_processor_spec.rb
+      xls_processor_spec.rb
+      google_drive_processor_spec.rb   # mocked worksheet interface
+    writers/
+      android_writer_spec.rb
+      ios_writer_spec.rb
+      swift_writer_spec.rb
+      json_writer_spec.rb
+      rails_writer_spec.rb
+      java_properties_writer_spec.rb
+      resx_writer_spec.rb
+  localio_spec.rb       # end-to-end: CSV fixture → writer → verify output files
+```
+
+### Fixture Data
+
+A single canonical `sample.csv` covers all test scenarios:
+- Normal keys with translations in 3 languages
+- Special characters: ampersands, ellipsis, printf format strings
+- Comment rows
+- Multi-level/nested keys (dot-separated) for JSON nesting tests
+
+The same fixture data drives all processor and writer tests for consistency.
+
+### Testing Strategy Per Layer
+
+**Models (Term, Segment):** Construction, attribute access, `is_comment?` detection.
+
+**Filter:** `only` and `except` with regex patterns against a fixed segment list.
+
+**Formatter:** All 4 modes (`:smart`, `:none`, `:camel_case`, `:snake_case`) against varied key strings.
+
+**Processors:**
+- CSV/XLSX/XLS: Parse real fixture files, assert correct Term extraction, language detection, comment handling
+- Google Drive: Mock the gem's worksheet interface, test the same parsing logic in isolation
+
+**TemplateHandler:** Render ERB templates, write to `Dir.mktmpdir`, assert output matches expected content.
+
+**Writers (all 7):** Feed a fixed Terms array → call writer → assert output files in a temp dir contain expected strings (spot-check key lines, not byte-perfect comparison).
+
+**Pipeline (`localio_spec.rb`):** CSV fixture → Android + JSON writers → verify files exist with correct content.
+
+### Key Test Helpers
+- Shared `let(:terms)` factory via RSpec shared contexts
+- `Dir.mktmpdir` for output isolation in all writer and template tests
+- No network calls; Google Drive mocked at the worksheet interface level
+
+## Phase 2: Dependency Updates
+
+| Gem | Current | Target | Notes |
+|-----|---------|--------|-------|
+| `google_drive` | `~> 1.0` | `~> 3.0` | API changed; processor needs update |
+| `spreadsheet` | `~> 1.0` | `~> 1.3` | Minor updates only |
+| `simple_xlsx_reader` | `~> 1.0` | `~> 2.0` | Breaking changes in v2 |
+| `nokogiri` | `~> 1.6` | `~> 1.16` | Mostly drop-in |
+| `micro-optparse` | `~> 1.2` | remove → stdlib `optparse` | Unmaintained |
+| `bundler` | `~> 1.3` | `~> 2.0` | Dev dep |
+| Ruby | `>= 1.9.2` | `>= 3.0` | Gemspec update |
+
+The green test suite from Phase 1 is the safety net — failures after dep updates pinpoint exactly what broke.