Make locale generation idempotent with force flag support (#2090)

## Summary

The `react_on_rails:locale` rake task is now idempotent, automatically
skipping generation when locale files are already up-to-date. This
addresses issue #2090 by making it safe to call multiple times (e.g.,
in Shakapacker's `precompile_hook`) without duplicate work or race
conditions.

## Key Improvements

- **Idempotent behavior**: Task skips regeneration when locale files
  are newer than source YAML files
- **Force flag**: Added `force=true` option to override timestamp
  checking and force regeneration
- **Clear messaging**: Outputs helpful messages when skipping or
  generating files
- **Safe coordination**: Can be called multiple times in precompile
  hooks, development servers, and CI without issues

## Changes

### Core Implementation

- `lib/tasks/locale.rake`: Added `force=true` parameter support and
  improved task description
- `lib/react_on_rails/locales/base.rb`: Modified `compile()` and
  `Base#initialize()` to accept and handle `force` parameter, added
  informative output messages

### Tests

- `spec/react_on_rails/locales_spec.rb`: Added tests for force
  parameter propagation to ToJson and ToJs
- `spec/react_on_rails/locales_to_js_spec.rb`: Added test verifying
  force flag bypasses timestamp checking

### Documentation

- `docs/building-features/i18n.md`: Added recommended pattern for using
  Shakapacker's `precompile_hook` with idempotent locale generation
- `CHANGELOG.md`: Added entry documenting the improvement

## Usage

### Normal use (skips if up-to-date):
```bash
bundle exec rake react_on_rails:locale
```

### Force regeneration:
```bash
bundle exec rake react_on_rails:locale force=true
```

### Recommended shakapacker.yml configuration:
```yaml
default: &default
  precompile_hook: "bundle exec rake react_on_rails:locale"
```

Fixes #2090

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: justin808

CHANGELOG.md

@@ -23,6 +23,10 @@ After a release, please make sure to run `bundle exec rake update_changelog`. Th
 
 Changes since the last non-beta release.
 
+#### Improved
+
+- **Idempotent Locale Generation**: The `react_on_rails:locale` rake task is now idempotent, automatically skipping generation when locale files are already up-to-date. This makes it safe to call multiple times (e.g., in Shakapacker's `precompile_hook`) without duplicate work. Added `force=true` option to override timestamp checking. [PR 2091](https://github.com/shakacode/react_on_rails/pull/2091) by [justin808](https://github.com/justin808).
+
 ### [v16.2.0.beta.12] - 2025-11-20
 
 #### Added

docs/building-features/i18n.md

@@ -21,10 +21,29 @@ You can use [Rails internationalization (i18n)](https://guides.rubyonrails.org/i
 
 3. The locale files must be generated before `yarn build` using `rake react_on_rails:locale`.
 
-   For development, you should adjust your startup scripts (`Procfile`s) so that they run `bundle exec rake react_on_rails:locale` before running any Webpack watch process (`yarn run build:development`).
+   **Recommended: Use Shakapacker's precompile_hook** (Shakapacker 9.3+)
 
-   If you are not using the React on Rails test helper,
-   you may need to configure your CI to run `bundle exec rake react_on_rails:locale` before any Webpack process as well.
+   The idempotent locale generation task can be safely called multiple times and will skip generation if files are already up-to-date. This makes it ideal for use with Shakapacker's `precompile_hook` feature:
+
+   ```yaml
+   # config/shakapacker.yml
+   default: &default
+     # Run locale generation before webpack compilation
+     # Safe to run multiple times - will skip if already built
+     precompile_hook: 'bundle exec rake react_on_rails:locale'
+   ```
+
+   This ensures locale files are always generated before webpack runs, whether in development, production, or CI. To force regeneration:
+
+   ```bash
+   bundle exec rake react_on_rails:locale force=true
+   ```
+
+   **Alternative: Manual coordination**
+
+   For development, you can adjust your startup scripts (`Procfile`s) to run `bundle exec rake react_on_rails:locale` before running any Webpack watch process (`yarn run build:development`).
+
+   If you are not using the React on Rails test helper, you may need to configure your CI to run `bundle exec rake react_on_rails:locale` before any Webpack process as well.
 
    > [!NOTE]
    > If you try to lint before running tests, and you depend on the test helper to build your locales, linting will fail because the translations won't be built yet.

lib/react_on_rails/locales/base.rb

@@ -4,7 +4,7 @@
 
 module ReactOnRails
   module Locales
-    def self.compile
+    def self.compile(force: false)
       config = ReactOnRails.configuration
       check_config_directory_exists(
         directory: config.i18n_dir, key_name: "config.i18n_dir",
@@ -15,9 +15,9 @@ def self.compile
         remove_if: "not using this i18n with React on Rails, or if you want to use all translation files"
       )
       if config.i18n_output_format&.downcase == "js"
-        ReactOnRails::Locales::ToJs.new
+        ReactOnRails::Locales::ToJs.new(force: force)
       else
-        ReactOnRails::Locales::ToJson.new
+        ReactOnRails::Locales::ToJson.new(force: force)
       end
     end
 
@@ -36,12 +36,17 @@ def self.check_config_directory_exists(directory:, key_name:, remove_if:)
     private_class_method :check_config_directory_exists
 
     class Base
-      def initialize
+      def initialize(force: false)
         return if i18n_dir.nil?
-        return unless obsolete?
+
+        if !force && !obsolete?
+          puts "Locale files are up to date, skipping generation. Use force=true to regenerate."
+          return
+        end
 
         @translations, @defaults = generate_translations
         convert
+        puts "Generated locale files in #{i18n_dir}"
       end
 
       private

lib/tasks/locale.rake

@@ -9,8 +9,13 @@ namespace :react_on_rails do
     Generate i18n javascript files
     This task generates javascript locale files: `translations.js` & `default.js` and places them in
     the "ReactOnRails.configuration.i18n_dir".
+
+    Options:
+      force=true - Force regeneration even if files are up to date
+                   Example: rake react_on_rails:locale force=true
   DESC
   task locale: :environment do
-    ReactOnRails::Locales.compile
+    force = ENV["force"] == "true"
+    ReactOnRails::Locales.compile(force: force)
   end
 end

spec/react_on_rails/locales_spec.rb

@@ -36,6 +36,22 @@ module ReactOnRails
 
         described_class.compile
       end
+
+      it "passes force parameter to ToJson" do
+        ReactOnRails.configuration.i18n_output_format = nil
+
+        expect(ReactOnRails::Locales::ToJson).to receive(:new).with(force: true)
+
+        described_class.compile(force: true)
+      end
+
+      it "passes force parameter to ToJs" do
+        ReactOnRails.configuration.i18n_output_format = "js"
+
+        expect(ReactOnRails::Locales::ToJs).to receive(:new).with(force: true)
+
+        described_class.compile(force: true)
+      end
     end
   end
 end

spec/react_on_rails/locales_to_js_spec.rb

@@ -50,6 +50,24 @@ module ReactOnRails
           described_class.new
           expect(File.mtime(translations_path)).to eq(ref_time)
         end
+
+        it "updates files when force is true" do
+          # Get initial mtime after first generation
+          initial_mtime = File.mtime(translations_path)
+
+          # Touch files to make them newer than YAML (up-to-date)
+          sleep 0.01 # Ensure timestamp difference
+          future_time = Time.current + 1.minute
+          FileUtils.touch(translations_path, mtime: future_time)
+          FileUtils.touch(default_path, mtime: future_time)
+
+          # Force regeneration even though files are up-to-date
+          described_class.new(force: true)
+
+          # New mtime should be different from the future_time we set
+          expect(File.mtime(translations_path)).not_to eq(future_time)
+          expect(File.mtime(translations_path)).to be > initial_mtime
+        end
       end
     end