rori18n-rails 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c8c49e7c74fc30821db32ed869c698211245a5c89df34ba7e2f2ed6334ac8005
-  data.tar.gz: 3c2f7300ac6a78679fc69b79850329d3f7ef73b4db91dd6674896eafd3073405
+  metadata.gz: adf721134937acd15e542d0763193c55f2a978d456b9bb61d7cfb16af37c761c
+  data.tar.gz: '08c22af47a7123428b315f4ce00a23c7d2c56d226c2c33f6b98cd8961e3d27ae'
 SHA512:
-  metadata.gz: 23c94d808d6f69d3c929ea5975a677177f3659c135a35bdb06ae2318a5cf2bd695ecb2aa46b529126143702759da30dca35015c106078649b15c4cb7813ee83e
-  data.tar.gz: 44ddc37a740aede0b62a9619e90e2ce6f3bb25bb11944504cb2ac34a3fcee5b74e0836bdf748396a8b3c54f672cf15a59a132fd55f6a33933d993e6d8350df0b
+  metadata.gz: 34c82ebfdfa96a300067ce7115fabe9055bcee1e11eaa97265c51655669edc74ea71dbbf99460689aa4f4df742f7b181a6ddb695e2be4684328b9bdb83d2e62b
+  data.tar.gz: 01d10bc140dc2654452d597f6b7ea4bb8d5ee23bdb99ff1f6e5358610df3d2a3634fd222f6b3f91eac41e31b8375dbc8ed7b06f440a3b8753a14617a701eb107

data/README.md

@@ -0,0 +1,360 @@
+# rori18n-rails
+
+Rails i18n toolchain. Extracts hardcoded strings, injects `t()` calls,
+translates via Google Cloud, deduplicates, and renames keys — all from one CLI.
+
+A drop-in replacement for `i18n-tasks` write commands with capabilities it
+lacks.
+
+```sh
+bin/rori18n generate --fix --root .
+```
+
+---
+
+## What it does that i18n-tasks can't
+
+| Capability                                   | Command           |
+| -------------------------------------------- | ----------------- |
+| Find every hardcoded string in ERB/Ruby      | `report`          |
+| Replace hardcoded strings with `t()` calls   | `generate --fix`  |
+| Merge sentence fragments into a single `t()` | `merge-fragments` |
+| Translate missing keys via Google Cloud      | `translate`       |
+| Rename a key across YAML and all callers     | `refactor-key`    |
+| Deduplicate identical strings to `shared.*`  | `consolidate`     |
+
+Also covers everything i18n-tasks does: lint, audit, prune.
+
+---
+
+## Install
+
+```ruby
+# Gemfile
+gem "rori18n-rails", group: :development
+```
+
+```sh
+bundle install
+bundle exec rails g rori18n:install   # creates bin/rori18n
+```
+
+The binary is downloaded automatically on first run and cached at
+`~/.rori18n/bin/`. Nothing to install manually.
+
+**Supported platforms:** macOS (Apple Silicon, Intel), Linux (x86_64).
+
+---
+
+## Usage
+
+All commands take `--root <path-to-rails-app>`. If you run from inside the app,
+`--root .` works.
+
+```sh
+bin/rori18n <command> --root <rails-app-root> [flags]
+```
+
+Or via Rake:
+
+```sh
+bundle exec rake rori18n:run ARGS="<command> [flags]"
+```
+
+---
+
+## Workflow
+
+### 1. See what needs extracting
+
+```sh
+bin/rori18n report --root .
+```
+
+Lists every hardcoded user-visible string in `app/` with file and line number.
+Read-only — nothing is changed.
+
+```sh
+# CI: fail if hardcoded strings exist in changed files
+git diff --name-only origin/main | \
+  bin/rori18n report --root . --fail-on-found --changed-files -
+```
+
+### 2. Extract strings to YAML
+
+```sh
+# Preview first
+bin/rori18n generate --root . --fix --dry-run
+
+# Apply
+bin/rori18n generate --root . --fix
+```
+
+One pass does everything:
+
+- Strings used in multiple files → written to `shared.{lang}.yml`
+- Unique strings → written to the matching topic file (`home.en.yml`, etc.)
+- Source files rewritten — hardcoded strings replaced with `t('key')` calls
+
+The app behaves identically after this step.
+
+```sh
+# Only process changed files
+git diff --name-only origin/main | \
+  bin/rori18n generate --root . --fix --changed-files -
+
+# Also create ES/FR skeleton files
+bin/rori18n generate --root . --fix --languages es,fr
+```
+
+### 3. Merge ERB fragments
+
+Sentences split across ERB interpolations are merged into a single `t()` call:
+
+```erb
+<%# Before %>
+<p>Hello <%= current_user.name %>, you have <%= count %> messages.</p>
+
+<%# After %>
+<p><%= t('.greeting', name: current_user.name, count: count) %></p>
+```
+
+```sh
+bin/rori18n merge-fragments --root . --dry-run
+bin/rori18n merge-fragments --root . --fix
+```
+
+Complex cases (boolean operators, nested HTML) are flagged for manual review and
+never auto-patched.
+
+### 4. Lint
+
+```sh
+bin/rori18n lint --root .
+```
+
+Exits `0` if every `t('key')` call resolves to a defined YAML entry. Exits `1`
+with `file:line: error: missing key "..."` output. Add to CI.
+
+### 5. Translate
+
+Requires a [Google Cloud Translation API](https://cloud.google.com/translate)
+service account key.
+
+```sh
+export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
+
+bin/rori18n translate --root . --to es,fr --dry-run
+bin/rori18n translate --root . --to es,fr
+```
+
+**Write safety:** only fills empty values and `TODO:`/`FIXME:` placeholders.
+Human translations are never overwritten.
+
+Results are cached — re-running the same source string does not hit the API
+again.
+
+```sh
+# Protect brand names from being translated
+bin/rori18n translate --root . --to es,fr \
+  --protect-words "Acme Corp,AbstractAPI"
+
+# Or from a file (one phrase per line)
+bin/rori18n translate --root . --to es,fr \
+  --protect-file .translate-dictionary.txt
+```
+
+### 6. Prune dead keys
+
+```sh
+bin/rori18n prune --root . --dry-run
+bin/rori18n prune --root .
+```
+
+Deletes YAML keys that no source file calls. Understands pluralization —
+`foo.one` / `foo.other` are kept when source calls `t('foo', count: n)`.
+
+---
+
+## All commands
+
+| Command           | What it does                                                |
+| ----------------- | ----------------------------------------------------------- |
+| `report`          | List hardcoded strings (read-only, CI-safe)                 |
+| `generate`        | Extract strings to YAML; optionally replace them with `t()` |
+| `merge-fragments` | Merge ERB sentence fragments into single `t()` calls        |
+| `lint`            | Exit 1 if any `t()` call references an undefined key        |
+| `audit`           | Report missing, orphaned, and empty keys                    |
+| `add-key`         | Add one key-value pair to the correct YAML file             |
+| `prune`           | Delete YAML keys never referenced in source                 |
+| `translate`       | Fill missing keys via Google Cloud Translation              |
+| `analyze`         | Find duplicate key names or identical values                |
+| `consolidate`     | Deduplicate keys and rewrite all callers in one pass        |
+| `refactor-key`    | Rename a key in YAML and all `t()` callers                  |
+
+---
+
+## Command reference
+
+### `report`
+
+```sh
+bin/rori18n report --root .
+bin/rori18n report --root . --fail-on-found
+bin/rori18n report --root . --erb-only
+
+# Limit to changed files (reads newline-separated paths from stdin)
+git diff --name-only origin/main | \
+  bin/rori18n report --root . --changed-files -
+```
+
+### `generate`
+
+```sh
+bin/rori18n generate --root . --fix --dry-run
+bin/rori18n generate --root . --fix
+bin/rori18n generate --root . --fix --languages es,fr
+bin/rori18n generate --root . --fix --safe-only    # only reuse existing keys
+bin/rori18n generate --root . --fix --no-shared    # skip shared.yml consolidation
+```
+
+### `merge-fragments`
+
+```sh
+bin/rori18n merge-fragments --root . --dry-run
+bin/rori18n merge-fragments --root . --fix
+```
+
+### `lint`
+
+```sh
+bin/rori18n lint --root .
+bin/rori18n lint --root . --lang fr
+```
+
+### `audit`
+
+```sh
+bin/rori18n audit --root . --orphaned        # in YAML, never called
+bin/rori18n audit --root . --missing         # called in source, not in YAML
+bin/rori18n audit --root . --all
+bin/rori18n audit --root . --empty-values
+bin/rori18n audit --root . --compare-locale fr
+```
+
+### `add-key`
+
+```sh
+bin/rori18n add-key --root . \
+  --key shared.buttons.save \
+  --value "Save changes"
+
+bin/rori18n add-key --root . --lang es \
+  --key shared.buttons.save \
+  --value "Guardar cambios"
+```
+
+Key is routed to the YAML file matching its top-level namespace
+(`shared.buttons.save` → `shared.en.yml`, `dashboard.foo` → `dashboard.en.yml`).
+
+### `prune`
+
+```sh
+bin/rori18n prune --root . --dry-run
+bin/rori18n prune --root .
+bin/rori18n prune --root . --lang fr
+bin/rori18n prune --root . --pattern 'shared\.common\.'
+```
+
+### `translate`
+
+```sh
+export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
+
+bin/rori18n translate --root . --to es,fr --dry-run
+bin/rori18n translate --root . --to es
+bin/rori18n translate --root . --to es --no-cache
+bin/rori18n translate --root . --to es --report-file reports/translate.json
+bin/rori18n translate --root . --to es --protect-words "Acme,AbstractAPI"
+```
+
+### `analyze`
+
+```sh
+bin/rori18n analyze --root .
+bin/rori18n analyze --root . --all     # include same-name, different-value keys
+bin/rori18n analyze --root . --source  # also scan ERB for hardcoded duplicates
+```
+
+### `consolidate`
+
+```sh
+bin/rori18n consolidate --root . --dry-run
+bin/rori18n consolidate --root .
+bin/rori18n consolidate --root . --no-prune   # rewrite callers, skip key deletion
+```
+
+### `refactor-key`
+
+```sh
+# Always dry-run first
+bin/rori18n refactor-key --root . \
+  --old shared.common.copy_btn \
+  --new shared.buttons.copy \
+  --dry-run
+
+bin/rori18n refactor-key --root . \
+  --old shared.common.copy_btn \
+  --new shared.buttons.copy
+
+# EN only (skip other locale files)
+bin/rori18n refactor-key --root . \
+  --old shared.common.copy_btn \
+  --new shared.buttons.copy \
+  --all-lang=false
+```
+
+---
+
+## CI integration
+
+```yaml
+# Minimal: lint only
+- name: Lint i18n keys
+  run: bin/rori18n lint --root .
+
+# Full: block hardcoded strings + lint
+- name: Check hardcoded strings
+  run: |
+    git diff --name-only origin/main | \
+      bin/rori18n report --root . --fail-on-found --changed-files -
+
+- name: Lint i18n keys
+  run: bin/rori18n lint --root .
+```
+
+---
+
+## YAML layout expected
+
+```
+config/locales/
+  en/
+    home.en.yml        # en.home.*
+    dashboard.en.yml   # en.dashboard.*
+    shared.en.yml      # en.shared.*
+  es/
+    home.es.yml
+    shared.es.yml
+  fr/
+    ...
+```
+
+---
+
+## vs i18n-tasks
+
+rori18n handles all write operations. `i18n-tasks` is still useful as a passive
+health-checker (`bundle exec i18n-tasks health`) — its scanner covers some
+Rails-specific patterns (before_actions, model translations) that static
+analysis misses. Use both: rori18n for writes, i18n-tasks health-only in CI.

data/lib/rori18n/version.rb

@@ -1,4 +1,4 @@
 module Rori18n
-  VERSION = "1.0.0"
+  VERSION = "1.2.0"
   CLI_VERSION = VERSION
 end

data/rori18n-rails.gemspec

@@ -5,9 +5,11 @@ Gem::Specification.new do |s|
   s.version     = Rori18n::VERSION
   s.authors     = ["Eliaz Bobadilla"]
   s.email       = ["eliaz.bobadilladev@gmail.com"]
-  s.summary     = "Use rori18n Go CLI as a Rails development dependency"
-  s.description = "Wraps the rori18n Go CLI tool so it behaves like a native Rails dev dependency. " \
-                  "Downloads the correct binary on first run. No manual installation required."
+  s.summary     = "Rails i18n toolchain: extract strings, inject t() calls, translate, prune, refactor keys"
+  s.description = "rori18n is a Rails i18n CLI that replaces i18n-tasks write commands and adds " \
+                  "capabilities it lacks: automatic hardcoded-string extraction from ERB, t() call " \
+                  "injection, ERB fragment merging, Google Cloud Translation, deduplication, and " \
+                  "key refactoring. "
   s.homepage    = "https://github.com/bobadilla-tech/rori18n"
   s.license     = "MIT"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rori18n-rails
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Eliaz Bobadilla
@@ -9,8 +9,10 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: Wraps the rori18n Go CLI tool so it behaves like a native Rails dev dependency.
-  Downloads the correct binary on first run. No manual installation required.
+description: 'rori18n is a Rails i18n CLI that replaces i18n-tasks write commands
+  and adds capabilities it lacks: automatic hardcoded-string extraction from ERB,
+  t() call injection, ERB fragment merging, Google Cloud Translation, deduplication,
+  and key refactoring. '
 email:
 - eliaz.bobadilladev@gmail.com
 executables:
@@ -18,6 +20,7 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- README.md
 - exe/rori18n
 - lib/generators/rori18n/install/install_generator.rb
 - lib/generators/rori18n/install/templates/binstub.tt
@@ -51,5 +54,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.6
 specification_version: 4
-summary: Use rori18n Go CLI as a Rails development dependency
+summary: 'Rails i18n toolchain: extract strings, inject t() calls, translate, prune,
+  refactor keys'
 test_files: []