i18n-js 4.2.4 → 5.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f067f8059ef5fe37c2fdb9624cf260e00b3eb60a87492aebccb0b13f170ff17d
-  data.tar.gz: 73acf779ba9a46921e44e4106e66eab2c5d05b7b1163cb93b2889abf446977e0
+  metadata.gz: 4651d246704c3470ac5139dec7d2351e4aad13866be1d51e20e6bcf960afa2aa
+  data.tar.gz: 43ba1c9e9f74c9032c17ee00fd54489b91275d23f559ff042a3b1c1300ddd3e9
 SHA512:
-  metadata.gz: a71ec7995b41c9e9c56168dccd1a87e1e872c3bfa98075c135aa9d6f4f0259fef6da8e8db81fd1fa63966775b5bd28185ee086a6206c0600b113827938b73412
-  data.tar.gz: be12ef7d7665f61d40abd05849cb25dc303c1679c08e6ed535123e9389cb5d968946b4d716d541bc5e10f8d1384040b7935e56aa0c84d682d0964a0698683d50
+  metadata.gz: d4b83c24cb85bcfd1badeef6ecc4e2955a138be41f5fbd68cf5122c21daa0c34b8e5df69a5c16739aca8f007dde7141f1cc35cc4ee9f9166c54754b6d8b33d61
+  data.tar.gz: 91a2fb161e6b7f3d1e698f92e49dabd46aa37bb15153ca6ce8f28849acd704204fff033c79ed7a06f599d2246ef9b8ae285a66d8165a2e538b42140e1d5e95a5

data/.github/workflows/ruby-tests.yml

@@ -9,14 +9,12 @@ on:
 
 jobs:
   build:
-    name:
-      Tests with Ruby ${{ matrix.ruby }}, Node ${{ matrix.node }} and ${{
-      matrix.gemfile }}
+    name: Tests with Ruby ${{ matrix.ruby }}, Node ${{ matrix.node }} and ${{ matrix.gemfile }}
     runs-on: "ubuntu-latest"
     strategy:
       fail-fast: false
       matrix:
-        ruby: ["3.3", "3.4"]
+        ruby: ["3.4", "3.5", "4.0"]
         node: ["22", "24"]
         gemfile:
           - Gemfile
@@ -25,26 +23,22 @@ jobs:
       github.actor != 'dependabot[bot]'
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - uses: actions/cache@v4
+      - uses: actions/cache@v5
         id: bundler-cache
         with:
           path: vendor/bundle
           key: >
-            ${{ runner.os }}-${{ matrix.ruby }}-gems-${{
-            hashFiles(matrix.gemfile) }}
-
-      - uses: actions/cache@v4
+            ${{ runner.os }}-${{ matrix.ruby }}-gems-${{ hashFiles(matrix.gemfile) }}
+      - uses: actions/cache@v5
         id: npm-cache
         with:
           path: vendor/bundle
           key: >
-            ${{ runner.os }}-${{ matrix.node }}-npm-${{
-            hashFiles('package.json') }}
-
+            ${{ runner.os }}-${{ matrix.node }}-npm-${{ hashFiles('package.json') }}
       - name: Set up Node
-        uses: actions/setup-node@v4.0.2
+        uses: actions/setup-node@v6.4.0
         with:
           node-version: ${{ matrix.node }}
 

data/CHANGELOG.md

@@ -11,6 +11,43 @@ Prefix your message with one of the following:
 - [Security] in case of vulnerabilities.
 -->
 
+## v5.0.0.rc1 - Jun 02, 2026
+
+- [Added] `embed_fallback_translations` plugin now supports `I18n.fallbacks`,
+  and will switch to it automatically if you're using a backend that includes
+  the `I18n::Backend::Fallbacks` module and have `I18n.fallbacks` configured.
+- [Changed] `i18n lint:translations` and `i18n lint:scripts` now support globs
+  in their `ignore` option.
+- [Removed] Previous versions allowed bare keys in lint's `:ignore` rule. This
+  is no longer supported; instead, use `*.key`.
+- [Removed] Remove `i18n check`; use `i18n lint:translations` instead.
+- [Fixed] Return the number of missing translations as the exit code when
+  running `i18n lint:scripts`.
+- [Changed] Plugin configuration moved from top-level keys to a `pipeline:`
+  array in the config file. Each entry requires a `plugin:` key identifying the
+  plugin and an `enabled:` key. Plugin-specific options are defined inline in
+  the same stage object.
+- [Changed] `I18nJS::Plugin.key` is now a class method returning a String.
+  Previously it was an instance method called `config_key` that returned a
+  Symbol.
+- [Changed] `I18nJS::Plugin#initialize` now accepts `plugin_config:` and
+  `main_config:` instead of a single `config:` argument.
+- [Changed] `I18nJS::Plugin#config` now returns only the plugin's own
+  configuration slice instead of the full main config.
+- [Changed] `I18nJS.initialize_plugins!` now returns the list of active plugin
+  instances. The `I18nJS.plugins` accessor has been removed.
+- [Changed] `I18nJS::Schema.root_keys` is now a frozen Array. Plugins no longer
+  need to register a root key in their `setup` method.
+- [Changed] Schema validation paths in `validate_schema` are now relative to the
+  plugin's own config root. Remove the leading `config_key` segment from all
+  paths passed to `schema.*` helpers.
+- [Removed] The `check:` root key is no longer recognised by the schema
+  validator. Remove it from your config file.
+- [Added] A single plugin class can now appear multiple times in the pipeline
+  with different configurations, each running as an independent instance.
+- [Changed] Export translations in parallel. To enable parallel mode, your
+  output file definition must include the `:locale` placeholder.
+
 ## v4.2.3 - Mar 29, 2023
 
 - [Fixed] Load plugins when running `i18n lint:*` commands.

data/MIGRATING_CONFIG_FOR_USERS.md

@@ -0,0 +1,200 @@
+# Migrating Your Configuration File
+
+This guide covers the changes you need to make to your `config/i18n.yml` (or
+equivalent) after the switch to the `pipeline:` API.
+
+---
+
+## What changed
+
+Plugin configuration used to live at the top level of the config file, each
+plugin using its own root key. All plugins are now listed in a single
+`pipeline:` array. The order of entries in the array determines the order in
+which plugins run.
+
+---
+
+## 1. `embed_fallback_translations`
+
+**Before**
+
+```yaml
+translations:
+  - file: app/javascript/locales/%{locale}.json
+    patterns:
+      - "*"
+
+embed_fallback_translations:
+  enabled: true
+```
+
+**After**
+
+```yaml
+translations:
+  - file: app/javascript/locales/%{locale}.json
+    patterns:
+      - "*"
+
+pipeline:
+  - plugin: embed_fallback_translations
+    enabled: true
+```
+
+---
+
+## 2. `export_files`
+
+**Before**
+
+```yaml
+translations:
+  - file: app/javascript/locales/%{locale}.json
+    patterns:
+      - "*"
+
+export_files:
+  enabled: true
+  files:
+    - template: path/to/template.erb
+      output: "%{dir}/%{base_name}.ts"
+```
+
+**After**
+
+```yaml
+translations:
+  - file: app/javascript/locales/%{locale}.json
+    patterns:
+      - "*"
+
+pipeline:
+  - plugin: export_files
+    enabled: true
+    files:
+      - template: path/to/template.erb
+        output: "%{dir}/%{base_name}.ts"
+```
+
+Plugin-specific keys (`files:` in this case) move into the pipeline stage
+object, directly alongside `plugin:` and `enabled:`.
+
+---
+
+## 3. Multiple plugins
+
+When you use more than one plugin, list them all under the same `pipeline:`
+key. The plugins run in the order they are listed.
+
+**Before**
+
+```yaml
+translations:
+  - file: app/javascript/locales/%{locale}.json
+    patterns:
+      - "*"
+
+embed_fallback_translations:
+  enabled: true
+
+export_files:
+  enabled: true
+  files:
+    - template: path/to/template.erb
+      output: "%{dir}/%{base_name}.ts"
+```
+
+**After**
+
+```yaml
+translations:
+  - file: app/javascript/locales/%{locale}.json
+    patterns:
+      - "*"
+
+pipeline:
+  - plugin: embed_fallback_translations
+    enabled: true
+
+  - plugin: export_files
+    enabled: true
+    files:
+      - template: path/to/template.erb
+        output: "%{dir}/%{base_name}.ts"
+```
+
+---
+
+## 4. Temporarily disabling a plugin
+
+Set `enabled: false` on the pipeline stage. The stage stays in the file so you
+can re-enable it without rewriting the config.
+
+```yaml
+pipeline:
+  - plugin: embed_fallback_translations
+    enabled: false   # temporarily disabled
+```
+
+Previously, removing the top-level key was the only way to disable a plugin.
+
+---
+
+## 5. Running the same plugin more than once
+
+The pipeline allows the same plugin to appear multiple times with different
+options. This was not possible with the old top-level key approach.
+
+```yaml
+pipeline:
+  - plugin: export_files
+    enabled: true
+    files:
+      - template: templates/esm.erb
+        output: "%{dir}/%{base_name}.mjs"
+
+  - plugin: export_files
+    enabled: true
+    files:
+      - template: templates/cjs.erb
+        output: "%{dir}/%{base_name}.cjs"
+```
+
+---
+
+## 6. The `check` key was removed
+
+The `check:` root key is no longer a recognised configuration option and will
+cause a validation error if present. If you used `check.ignore` to suppress
+known-missing translation keys, move those entries to `lint_translations.ignore`
+— it serves the same purpose.
+
+**Before**
+
+```yaml
+check:
+  ignore:
+    - "es.bye"
+    - "pt.bye"
+```
+
+**After**
+
+```yaml
+lint_translations:
+  ignore:
+    - "es.bye"
+    - "pt.bye"
+```
+
+If your `check:` block contained no `ignore:` list, delete it entirely.
+
+---
+
+## Quick checklist
+
+- [ ] Remove the top-level `embed_fallback_translations:` block and replace with a `pipeline:` entry
+- [ ] Remove the top-level `export_files:` block and replace with a `pipeline:` entry (move `files:` into the stage)
+- [ ] Do the same for any third-party plugin that had its own top-level key
+- [ ] Move `check.ignore` entries to `lint_translations.ignore`, then delete the `check:` block
+- [ ] Verify the `pipeline:` key is a YAML sequence (starts with `-`), not a mapping

data/MIGRATING_PLUGINS_FOR_PLUGIN_DEVELOPERS.md

@@ -0,0 +1,299 @@
+# Migrating Plugins to the Pipeline API
+
+This guide covers the breaking changes to the plugin API introduced in the
+commit that switched plugins from top-level config keys to a `pipeline` array.
+
+---
+
+## Overview of changes
+
+| Area | Before | After |
+|------|--------|-------|
+| Config location | Top-level key per plugin | `pipeline:` array |
+| Key method | `config_key` (instance, Symbol) | `Plugin.key` (class method, String) |
+| Constructor | `initialize(config:)` | `initialize(plugin_config:, main_config:)` |
+| `config` accessor | `main_config[config_key]` | plugin-specific hash from pipeline entry |
+| `setup` | registers root schema key | no schema registration needed |
+| `validate_schema` paths | prefixed with `config_key` | relative to plugin config root |
+| `I18nJS.plugins` | global accessor | return value of `initialize_plugins!` |
+| `Schema.root_keys` | mutable Set | frozen Array |
+
+---
+
+## 1. Update the config file
+
+Plugin configuration no longer lives at the top level of the YAML file. Move
+every plugin block into the `pipeline:` array and add a `plugin:` key that
+identifies the plugin by its inferred key name (snake_case, no `Plugin`
+suffix).
+
+**Before**
+
+```yaml
+translations:
+  - file: app/javascript/locales/%{locale}.json
+    patterns:
+      - "*"
+
+embed_fallback_translations:
+  enabled: true
+
+export_files:
+  enabled: true
+  files:
+    - template: templates/export.erb
+      output: "%{dir}/%{base_name}-%{digest}.ts"
+```
+
+**After**
+
+```yaml
+translations:
+  - file: app/javascript/locales/%{locale}.json
+    patterns:
+      - "*"
+
+pipeline:
+  - plugin: embed_fallback_translations
+    enabled: true
+
+  - plugin: export_files
+    enabled: true
+    files:
+      - template: templates/export.erb
+        output: "%{dir}/%{base_name}-%{digest}.ts"
+```
+
+All plugin-specific keys (like `files:` above) now live directly inside the
+pipeline stage object, alongside `plugin:` and `enabled:`.
+
+---
+
+## 2. Rename `config_key` to `Plugin.key`
+
+The method that infers the plugin's identifier moved from an **instance**
+method returning a Symbol to a **class** method returning a String.
+
+**Before**
+
+```ruby
+# instance method, returns Symbol
+def config_key
+  :my_plugin
+end
+```
+
+**After**
+
+```ruby
+# class method, returns String
+def self.key
+  "my_plugin"
+end
+```
+
+In most cases you do **not** need to override this method at all — it is
+automatically inferred from the class name:
+
+| Class name | Inferred key |
+|------------|-------------|
+| `SamplePlugin` | `"sample"` |
+| `EmbedFallbackTranslationsPlugin` | `"embed_fallback_translations"` |
+| `FetchFromHTTPPlugin` | `"fetch_from_http"` |
+
+Override only if the inferred name does not match what you want to expose in the
+config file.
+
+---
+
+## 3. Update the constructor
+
+The constructor signature changed. `config:` (the full main config) was
+replaced by two keyword arguments.
+
+**Before**
+
+```ruby
+def initialize(config:)
+  @main_config = config
+  @schema      = I18nJS::Schema.new(@main_config)
+end
+```
+
+**After**
+
+The base class handles initialization. You rarely need to override `initialize`
+at all. If you do, call `super` and use the provided accessors:
+
+```ruby
+def initialize(plugin_config:, main_config:)
+  super
+  # @config      => plugin-specific hash (the pipeline stage, minus :plugin key)
+  # @main_config => full config hash
+  # @schema      => Schema.new(@config)
+end
+```
+
+---
+
+## 4. Use `config` instead of `main_config[config_key]`
+
+`config` now returns only the plugin's own slice of configuration (the pipeline
+stage hash, with the `plugin:` key removed). You no longer need to dig into
+`main_config` to find your plugin's settings.
+
+**Before**
+
+```ruby
+def transform(translations:)
+  return translations unless main_config[config_key][:enabled]
+  # work with main_config[config_key][:my_option]
+end
+```
+
+**After**
+
+```ruby
+def transform(translations:)
+  # work with config[:my_option] directly
+end
+```
+
+`enabled?` is also handled by the base class and returns `config[:enabled]`.
+Only enabled plugins are placed in the pipeline, so you rarely need to check
+`enabled?` inside `transform`.
+
+---
+
+## 5. Remove schema root key registration from `setup`
+
+Plugins used to register their top-level config key so the schema validator
+wouldn't reject it. This is no longer necessary — the `pipeline:` array is
+already a recognised root key, and each stage is validated generically.
+
+**Before**
+
+```ruby
+def setup
+  I18nJS::Schema.root_keys << config_key
+end
+```
+
+**After**
+
+```ruby
+def setup
+  # plugin-specific setup only, no schema registration needed
+end
+```
+
+If `setup` contained only the `root_keys <<` line, you can delete the method
+entirely.
+
+---
+
+## 6. Update `validate_schema` paths
+
+`Schema` is now initialized with the plugin's own config hash rather than the
+full main config. All paths passed to schema helpers are therefore **relative to
+the plugin config root**, not the global config root.
+
+**Before**
+
+```ruby
+def validate_schema
+  valid_keys = %i[enabled files]
+
+  schema.expect_required_keys(keys: valid_keys, path: [config_key])
+  schema.reject_extraneous_keys(keys: valid_keys, path: [config_key])
+  schema.expect_array_with_items(path: [config_key, :files])
+
+  config[:files].each_with_index do |_, index|
+    export_keys = %i[template output]
+    schema.expect_required_keys(keys: export_keys, path: [config_key, :files, index])
+    schema.expect_type(path: [config_key, :files, index, :template], types: String)
+  end
+end
+```
+
+**After**
+
+```ruby
+def validate_schema
+  valid_keys = %i[enabled files]
+
+  schema.expect_required_keys(keys: valid_keys)          # path defaults to []
+  schema.reject_extraneous_keys(keys: valid_keys)
+  schema.expect_array_with_items(path: [:files])         # relative path
+
+  export_keys = %i[template output]
+  config[:files].each_with_index do |_, index|
+    schema.expect_required_keys(keys: export_keys, path: [:files, index])
+    schema.expect_type(path: [:files, index, :template], types: String)
+  end
+end
+```
+
+The rule: **drop the leading `config_key` segment from every path**.
+
+---
+
+## 7. Stop using `I18nJS.plugins`
+
+The global `I18nJS.plugins` accessor was removed. `initialize_plugins!` now
+returns the list of active plugin instances directly.
+
+**Before**
+
+```ruby
+I18nJS.initialize_plugins!(config:)
+I18nJS.plugins.each { |p| p.do_something }
+```
+
+**After**
+
+```ruby
+plugins = I18nJS.initialize_plugins!(config:)
+plugins.each { |p| p.do_something }
+```
+
+If you were calling `I18nJS.plugins.clear` in tests, switch to
+`I18nJS.available_plugins.clear` (which clears registered plugin classes) or
+simply stop clearing — `initialize_plugins!` now reads solely from the
+`pipeline:` config so stale instances are never carried over.
+
+---
+
+## 8. One plugin class, multiple pipeline stages
+
+A single plugin class can now appear **multiple times** in the pipeline with
+different configurations. Each entry creates an independent plugin instance.
+Each instance receives its own `config` hash.
+
+```yaml
+pipeline:
+  - plugin: export_files
+    enabled: true
+    files:
+      - template: templates/esm.erb
+        output: "app/js/%{base_name}.mjs"
+
+  - plugin: export_files
+    enabled: true
+    files:
+      - template: templates/cjs.erb
+        output: "app/js/%{base_name}.cjs"
+```
+
+---
+
+## Quick checklist
+
+- [ ] Move all plugin blocks from the top level into a `pipeline:` array
+- [ ] Add a `plugin:` key to each pipeline stage
+- [ ] Rename `config_key` instance method to `self.key` class method; change return type from Symbol to String
+- [ ] Remove `initialize` override if it only delegated to `super`; otherwise update signature to `(plugin_config:, main_config:)`
+- [ ] Replace `main_config[config_key][:option]` with `config[:option]`
+- [ ] Delete `setup` if it only registered a root schema key
+- [ ] Drop the leading `config_key` segment from all `schema.*` paths in `validate_schema`
+- [ ] Replace `I18nJS.plugins` with the return value of `initialize_plugins!`