i18n-js 4.0.0.alpha4 → 4.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ecf4853a33adc9a67520a585c733a55e7b05e07bdc436830c519213bfc728b6
-  data.tar.gz: 5a1b68a4182bc30fcc3c57438ab226ba72a97a7f16dd6c29ac938106f4c5e00c
+  metadata.gz: fb5f60568907f90a59b7d19a6b2f61cf9a3fff95ea419b1b8b31deab16529dc6
+  data.tar.gz: ca65b2bf6717b93218092e8c994cdbac8af6bc69fddab421ebef976c87dc5503
 SHA512:
-  metadata.gz: f8468f07c440fa8c29c84a6550ef8b7d5914cf08ce93d0b02f77caf65838a4057f8a7653cc221c33a1dfaf1ab0486aa195a368248ca9509af4af7071ab76ddaa
-  data.tar.gz: cb3822d5fe66aa90b20a4a596869a0adb93c3154d5877f66b1374794961536bc2916c051f8d5ce5f61d2d57c66951c25b477f8b808b7d737b39941875e545afb
+  metadata.gz: 3e33c8605b5197cbdc6a8f30ef1cb7e5f911f84dd177d488489fcfc82e5dd2b8fb3e387b0fe89683c3e71c6025ff7b47685163317540c4e2c5c756936660be55
+  data.tar.gz: b4367db58b89392c42c94121ccdde7179e1ea455de6c20685ded2c034304ce4c8c44cbfa1a4967610443e4f91116058ee86bc14d2e913a2c6006ee648c189dd9

data/CHANGELOG.md

@@ -11,6 +11,13 @@ Prefix your message with one of the following:
 - [Security] in case of vulnerabilities.
 -->
 
-## Unreleased
+## v4.0.1
 
-- Initial release.
+- [Fixed] Shell out export to avoid handling I18n reloading heuristics.
+- [Changed] `I18nJS.listen` now accepts a directories list to watch.
+- [Changed] `I18nJS.listen` now accepts
+  [listen](https://rubygems.org/gems/listen) options via `:options`.
+
+## Jul 29, 2022
+
+- Official release of i18n-js v4.0.0.

data/MIGRATING_FROM_V3_TO_V4.md

@@ -0,0 +1,191 @@
+# Migrating from v3 to v4
+
+I18n-js v4 is a breaking change release and diverges quite a lot from how the
+previous version worked. This guides summarizes the process of upgrading an app
+that uses i18n-js v3 to v4.
+
+## Development
+
+Previously, you could use a middleware to export translations (some people even
+used this in production 😬). In development, you can now use whatever your want,
+because i18n-js doesn't make any assumptions. All you need to do is running
+`i18n export`, either manually or by using something that listens to file
+changes.
+
+If you like watchman, you can use something like this:
+
+```bash
+#!/usr/bin/env bash
+
+root=`pwd`
+
+watchman watch-del "$root"
+watchman watch-project "$root"
+watchman trigger-del "$root" i18n
+
+watchman -j <<-JSON
+[
+  "trigger",
+  "$root",
+  {
+    "name": "i18n",
+    "expression": [
+      "anyof",
+      ["match", "config/locales/**/*.yml", "wholename"],
+      ["match", "config/locales/**/*.po", "wholename"],
+      ["match", "config/i18n.yml", "wholename"]
+    ],
+    "command": ["i18n", "export"]
+  }
+]
+JSON
+
+# If you're running this through Foreman, then uncomment the following lines:
+# while true; do
+#   sleep 1
+# done
+```
+
+You can also use guard. Make sure you have both
+[guard](https://rubygems.org/packages/guard) and
+[guard-compat](https://rubygems.org/packages/guard-compat) installed and use
+Guardfile file with the following contents:
+
+```ruby
+guard(:"i18n-js",
+      run_on_start: true,
+      config_file: "./config/i18n.yml",
+      require_file: "./config/environment.rb") do
+  watch(%r{^config/locales/.+\.(yml|po)$})
+  watch(%r{^config/i18n.yml$})
+  watch("Gemfile")
+end
+```
+
+To run guard, use `guard start -i`.
+
+Finally, you can use [listen](https://rubygems.org/gems/listen). Create the file
+`config/initializers/i18n.rb` with the following content:
+
+```ruby
+Rails.application.config.after_initialize do
+  require "i18n-js/listen"
+  # This will only run in development.
+  I18nJS.listen
+end
+```
+
+> **Warning**:
+>
+> No matter which approach you choose, the idea is that you _precompile_ your
+> translations when going to production. DO NOT RUN any of the above in
+> production.
+
+## Exporting translations
+
+The build process for i18n now relies on an external CLI called `i18n`. All you
+need to do is executing `i18n export` in your build step to generate the json
+files for your translations.
+
+## Using your translations
+
+The JavaScript package is now a separate thing and need to be installed using
+your favorite tooling (e.g. yarn, npm, pnpm, etc).
+
+```console
+$ yarn add i18n-js@latest
+$ npm i --save-dev i18n-js@latest
+```
+
+From now on, the way you load translations and set up I18n-js is totally up to
+you, but means you need to load the json files and attach to the I18n-js
+instance. This is how I do it in a project I'm doing right now (Rails 7 +
+esbuild + TypeScript). First, we need to load the I18n-js configuration from the
+main JavaScript file:
+
+```typescript
+// app/javascript/application.ts
+import { i18n } from "./config/i18n";
+```
+
+Then we need to load our translations and instantiate the I18n-js class.
+
+```typescript
+// app/javascript/config/i18n.ts
+import { I18n } from "i18n-js";
+import translations from "translations.json";
+
+// Fetch user locale from html#lang.
+// This value is being set on `app/views/layouts/application.html.erb` and
+// is inferred from `ACCEPT-LANGUAGE` header.
+const userLocale = document.documentElement.lang;
+
+export const i18n = new I18n();
+i18n.store(translations);
+i18n.defaultLocale = "en";
+i18n.enableFallback = true;
+i18n.locale = userLocale;
+```
+
+The best thing about the above is that it is a pretty straightforward pattern in
+the JavaScript community. It doesn't rely on specific parts from Sprockets (I'm
+not even using it on my projects) or eRb files.
+
+## Ruby on Rails
+
+### Upgrading the configuration file
+
+The configuration file loaded from `config/i18nyml` has changed. Given the v3
+configuration below
+
+```yaml
+---
+translations:
+  - file: "app/assets/javascripts/date_formats.js"
+    only: "*.date.formats"
+  - file: "app/assets/javascripts/other.js"
+    only: ["*.activerecord", "*.admin.*.title"]
+  - file: "app/assets/javascripts/everything_else.js"
+    except:
+      - "*.activerecord"
+      - "*.admin.*.title"
+      - "*.date.formats"
+```
+
+the equivalent configuration file for v4 would be
+
+```yaml
+---
+translations:
+  - file: "app/assets/javascripts/date_formats.js"
+    patterns:
+      - "*.date.formats"
+  - file: "app/assets/javascripts/other.js"
+    patterns:
+      - "*.activerecord"
+      - "*.admin.*.title"
+  - file: "app/assets/javascripts/everything_else.js"
+    patterns:
+      # Notice the exclamation mark.
+      - "!*.activerecord"
+      - "!*.admin.*.title"
+      - "!*.date.formats"
+```
+
+Other configuration options:
+
+- `export_i18n_js`: removed without an equivalent
+- `fallbacks`: removed without an equivalent
+- `js_available_locales`: removed (on v4 you can use groups, like in
+  `{pt-BR,en}.*`)
+- `namespace`: removed without an equivalent
+- `sort_translation_keys`: removed (on v4 keys will always be sorted)
+- `translations[].prefix`: removed without an equivalent
+- `translations[].pretty_print`: removed (on v4 files will always be exported in
+  a readable format)
+
+### Placeholders
+
+Previously, v3 had the `%{locale}` placeholder, which can be used as part of the
+directory and/or file name. Now, the syntax is just `:locale`. Additionally, you
+can also use `:digest`, which uses a MD5 hex digest of the exported file.

data/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img width="250" height="58" src="https://github.com/fnando/i18n-js/raw/main/i18njs.png" alt="i18n.js">
+  <img width="250" height="58" src="https://github.com/fnando/i18n-js/raw/main/images/i18njs.png" alt="i18n.js">
 </p>
 
 <p align="center">
@@ -12,8 +12,8 @@
   <small>
     Oh, you don't use Ruby? No problem! You can still use i18n-js
     <br>
-    and the 
-    <a href="https://www.npmjs.com/package/i18n-js/v/next">companion JavaScript package</a>.
+    and the
+    <a href="https://www.npmjs.com/package/i18n-js/v/latest">companion JavaScript package</a>.
   </small>
 </p>
 
@@ -24,8 +24,6 @@
   <a href="https://tldrlegal.com/license/mit-license"><img src="https://img.shields.io/:License-MIT-blue.svg" alt="MIT License"></a>
 </p>
 
-![This branch contains the code for v4, our next major release.](https://messages-svg.herokuapp.com/warning.svg?message=This%20branch%20contains%20the%20code%20for%20v4%2C%20our%20next%20major%20release.)
-
 ## Installation
 
 ```bash
@@ -35,7 +33,7 @@ gem install i18n-js
 Or add the following line to your project's Gemfile:
 
 ```ruby
-gem "i18n-js", "~> 4.0.0.alpha1"
+gem "i18n-js"
 ```
 
 ## Usage
@@ -47,6 +45,14 @@ About patterns:
   - `*.messages.*`
 - Patterns starting with `!` are excluded.
   - `!*.activerecord.*` will exclude all ActiveRecord translations.
+- You can use groups:
+  - `{pt-BR,en}.js.*` will include only `pt-BR` and `en` translations, even if
+    more languages are available.
+
+> **Note**:
+>
+> Patterns use [glob](https://rubygems.org/gems/glob), so check it out for the
+> most up-to-date documentation about what's available.
 
 The config file:
 
@@ -111,9 +117,37 @@ default locale. Here's an example:
 This command will exist with status 1 whenever there are missing translations.
 This way you can use it as a CI linting.
 
+You can ignore keys by adding a list to the config file:
+
+```yml
+---
+translations:
+  - file: app/frontend/locales/en.json
+    patterns:
+      - "*"
+      - "!*.activerecord"
+      - "!*.errors"
+      - "!*.number.nth"
+
+  - file: app/frontend/locales/:locale.:digest.json
+    patterns:
+      - "*"
+
+check:
+  ignore:
+    - en.mailer.login.subject
+    - en.mailer.login.body
+```
+
+> **Note**:
+>
+> In order to avoid mistakenly ignoring keys, this configuration option only
+> accepts the full translation scope, rather than accepting a pattern like
+> `pt.ignored.scope.*`.
+
 ## Automatically export translations
 
-### Using watchman
+### Using [watchman](https://facebook.github.io/watchman/)
 
 Create a script at `bin/i18n-watch`.
 
@@ -158,11 +192,11 @@ line to your Procfile:
 i18n: ./bin/i18n-watch
 ```
 
-### Using guard
+### Using [guard](https://rubygems.org/gems/guard)
 
-Install [guard](https://rubygems.org/packages/guard) and
-[guard-compat](https://rubygems.org/packages/guard-compat). Then create a
-Guardfile with the following configuration:
+Install [guard](https://rubygems.org/gems/guard) and
+[guard-compat](https://rubygems.org/gems/guard-compat). Then create a Guardfile
+with the following configuration:
 
 ```ruby
 guard(:"i18n-js",
@@ -180,7 +214,7 @@ accordingly.
 
 Now you can run `guard start -i`.
 
-### Using listen
+### Using [listen](https://rubygems.org/gems/listen)
 
 Create a file under `config/initializers/i18n.rb` with the following content:
 
@@ -192,8 +226,21 @@ end
 ```
 
 The code above will watch for changes based on `config/i18n.yml` and
-`config/locales`. You can customize these options with
-`I18nJS.listen(config_file: "config/i18n.yml", locales_dir: "config/locales")`.
+`config/locales`. You can customize these options:
+
+- `config_file` - i18n-js configuration file
+- `locales_dir` - one or multiple directories to watch for locales changes
+- `options` - passed directly to [listen](https://github.com/guard/listen/#options)
+
+Example:
+
+```ruby
+I18nJS.listen(
+  config_file: "config/i18n.yml",
+  locales_dir: ["config/locales", "app/views"],
+  options: {only: %r{.yml$}
+)
+```
 
 ### Integrating with your frontend
 
@@ -203,6 +250,13 @@ that loads all the exported translation.
 
 ### FAQ
 
+#### I'm running v3. Is there a migration plan?
+
+[There's a document](https://github.com/fnando/i18n-js/tree/main/MIGRATING_FROM_V3_TO_V4.md)
+outlining some of the things you need to do to migrate from v3 to v4. It may not
+be as complete as we'd like it to be, so let's know if you face any issues
+during the migration is not outline is that document.
+
 #### How can I export translations without having a database around?
 
 Some people may have a build process using something like Docker that don't
@@ -222,9 +276,11 @@ require "action_view/railtie"
 I18n.load_path += Dir["./config/locales/**/*.yml"]
 ```
 
-Notice that you may not need to load ActiveSupport and ActionView lines, or even
-may need to add additional requires for other libs. With this approach you have
-full control on what's going to be loaded.
+> **Note**:
+>
+> You may not need to load ActiveSupport and ActionView lines, or even may need
+> to add additional requires for other libs. With this approach you have full
+> control on what's going to be loaded.
 
 ## Maintainer
 

data/i18n-js.gemspec

@@ -28,7 +28,7 @@ Gem::Specification.new do |spec|
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
     `git ls-files -z`
       .split("\x0")
-      .reject {|f| f.match(%r{^(test|spec|features)/}) }
+      .reject {|f| f.match(%r{^(test|spec|features|images)/}) }
   end
 
   spec.bindir        = "exe"

data/lib/guard/i18n-js.rb

@@ -53,13 +53,30 @@ module Guard
       info("Changes detected: #{changes.join(', ')}") if changes
 
       @current_thread = Thread.new do
-        require @require_file
-        ::I18nJS.call(config_file: @config_file)
+        capture do
+          system "i18n",
+                 "export",
+                 "--config",
+                 config_file.to_s,
+                 "--require",
+                 require_file.to_s,
+                 "--quiet"
+        end
       end
 
       current_thread.join
     end
 
+    def capture
+      original = $stdout
+      $stdout = StringIO.new
+      yield
+    rescue StandardError
+      # noop
+    ensure
+      $stdout = original
+    end
+
     def validate_file(key, file)
       return true if file && File.file?(file)
 
@@ -68,11 +85,11 @@ module Guard
     end
 
     def error(message)
-      ::Guard::UI.error "[guard-i18n-js] #{message}"
+      ::Guard::UI.error "[i18n-js] #{message}"
     end
 
     def info(message)
-      ::Guard::UI.info "[guard-i18n-js] #{message}"
+      ::Guard::UI.info "[i18n-js] #{message}"
     end
   end
 end

data/lib/i18n-js/cli/check_command.rb

@@ -69,9 +69,14 @@ module I18nJS
           )
         end
 
+        config = Glob::SymbolizeKeys.call(YAML.load_file(config_file))
+        Schema.validate!(config)
+
         load_require_file!(require_file) if require_file
+
         default_locale = I18n.default_locale
         available_locales = I18n.available_locales
+        ignored_keys = config.dig(:check, :ignore) || []
 
         mapping = available_locales.each_with_object({}) do |locale, buffer|
           buffer[locale] =
@@ -81,21 +86,50 @@ module I18nJS
 
         default_locale_keys = mapping.delete(default_locale)
 
+        if ignored_keys.any?
+          ui.stdout_print "=> Check #{options[:config_file].inspect} for " \
+                          "ignored keys."
+        end
+
         ui.stdout_print "=> #{default_locale}: #{default_locale_keys.size} " \
                         "translations"
 
         total_missing_count = 0
 
         mapping.each do |locale, partial_keys|
-          extraneous = partial_keys - default_locale_keys
-          missing = default_locale_keys - (partial_keys - extraneous)
+          ignored_count = 0
+
+          # Compute list of filtered keys (i.e. keys not ignored)
+          filtered_keys = partial_keys.reject do |key|
+            key = "#{locale}.#{key}"
+
+            ignored = ignored_keys.include?(key)
+            ignored_count += 1 if ignored
+            ignored
+          end
+
+          extraneous = (partial_keys - default_locale_keys).reject do |key|
+            key = "#{locale}.#{key}"
+            ignored = ignored_keys.include?(key)
+            ignored_count += 1 if ignored
+            ignored
+          end
+
+          missing = (default_locale_keys - (filtered_keys - extraneous))
+                    .reject {|key| ignored_keys.include?("#{locale}.#{key}") }
+
+          ignored_count += extraneous.size
           total_missing_count += missing.size
+
           ui.stdout_print "=> #{locale}: #{missing.size} missing, " \
-                          "#{extraneous.size} extraneous"
+                          "#{extraneous.size} extraneous, " \
+                          "#{ignored_count} ignored"
 
           all_keys = (default_locale_keys + extraneous + missing).uniq.sort
 
           all_keys.each do |key|
+            next if ignored_keys.include?("#{locale}.#{key}")
+
             label = if extraneous.include?(key)
                       ui.yellow("extraneous")
                     elsif missing.include?(key)

data/lib/i18n-js/cli/export_command.rb

@@ -27,6 +27,14 @@ module I18nJS
           options[:require_file] = require_file
         end
 
+        opts.on(
+          "-q",
+          "--quiet",
+          "A Ruby file that must be loaded"
+        ) do |quiet|
+          options[:quiet] = quiet
+        end
+
         opts.on("-h", "--help", "Prints this help") do
           ui.exit_with opts.to_s
         end
@@ -39,11 +47,11 @@ module I18nJS
           ui.fail_with("=> ERROR: you need to specify the config file")
         end
 
-        ui.stdout_print("=> Config file:", options[:config_file].inspect)
+        log("=> Config file:", options[:config_file].inspect)
         config_file = File.expand_path(options[:config_file])
 
         if options[:require_file]
-          ui.stdout_print("=> Require file:", options[:require_file].inspect)
+          log("=> Require file:", options[:require_file].inspect)
           require_file = File.expand_path(options[:require_file])
         end
 
@@ -66,7 +74,13 @@ module I18nJS
           I18nJS.call(config_file: config_file)
         end
 
-        ui.stdout_print("=> Done in #{time.round(2)}s")
+        log("=> Done in #{time.round(2)}s")
+      end
+
+      private def log(*args)
+        return if options[:quiet]
+
+        ui.stdout_print(*args)
       end
 
       private def set_defaults!

data/lib/i18n-js/listen.rb

@@ -7,7 +7,8 @@ module I18nJS
 
   def self.listen(
     config_file: Rails.root.join("config/i18n.yml"),
-    locales_dir: Rails.root.join("config/locales")
+    locales_dir: Rails.root.join("config/locales"),
+    options: {}
   )
     return unless Rails.env.development?
     return if started
@@ -18,12 +19,14 @@ module I18nJS
 
     self.started = true
 
+    locales_dirs = Array(locales_dir)
+
     relative_paths =
-      [config_file, locales_dir].map {|path| relative_path(path) }
+      [config_file, *locales_dirs].map {|path| relative_path(path) }
 
     debug("Watching #{relative_paths.inspect}")
 
-    listener(config_file, locales_dir.to_s).start
+    listener(config_file, locales_dirs.map(&:to_s), options).start
     I18nJS.call(config_file: config_file)
   end
 
@@ -43,12 +46,12 @@ module I18nJS
     @logger ||= ActiveSupport::TaggedLogging.new(Rails.logger)
   end
 
-  def self.listener(config_file, locales_dir)
-    paths = [File.dirname(config_file), locales_dir]
+  def self.listener(config_file, locales_dirs, options)
+    paths = [File.dirname(config_file), *locales_dirs]
 
-    Listen.to(*paths) do |changed, added, removed|
+    Listen.to(*paths, options) do |changed, added, removed|
       changes = compute_changes(
-        [config_file, locales_dir],
+        [config_file, *locales_dirs],
         changed,
         added,
         removed
@@ -58,11 +61,22 @@ module I18nJS
 
       debug(changes.map {|key, value| "#{key}=#{value.inspect}" }.join(", "))
 
-      ::I18n.backend.reload!
-      I18nJS.call(config_file: config_file)
+      capture do
+        system "i18n", "export", "--config", config_file.to_s
+      end
     end
   end
 
+  def self.capture
+    original = $stdout
+    $stdout = StringIO.new
+    yield
+  rescue StandardError
+    # noop
+  ensure
+    $stdout = original
+  end
+
   def self.compute_changes(paths, changed, added, removed)
     paths = paths.map {|path| relative_path(path) }
 

data/lib/i18n-js/schema.rb

@@ -4,8 +4,9 @@ module I18nJS
   class Schema
     InvalidError = Class.new(StandardError)
 
-    ROOT_KEYS = %i[translations].freeze
+    ROOT_KEYS = %i[translations check].freeze
     REQUIRED_ROOT_KEYS = %i[translations].freeze
+    REQUIRED_CHECK_KEYS = %i[ignore].freeze
     REQUIRED_TRANSLATION_KEYS = %i[file patterns].freeze
     TRANSLATION_KEYS = %i[file patterns].freeze
 
@@ -25,6 +26,17 @@ module I18nJS
       expect_required_keys(REQUIRED_ROOT_KEYS, target)
       reject_extraneous_keys(ROOT_KEYS, target)
       validate_translations
+      validate_check
+    end
+
+    def validate_check
+      return unless target.key?(:check)
+
+      check = target[:check]
+
+      expect_type(:check, check, Hash, target)
+      expect_required_keys(REQUIRED_CHECK_KEYS, check)
+      expect_type(:ignore, check[:ignore], Array, check)
     end
 
     def validate_translations

data/lib/i18n-js/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module I18nJS
-  VERSION = "4.0.0.alpha4"
+  VERSION = "4.0.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: i18n-js
 version: !ruby/object:Gem::Version
-  version: 4.0.0.alpha4
+  version: 4.0.1
 platform: ruby
 authors:
 - Nando Vieira
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-07-21 00:00:00.000000000 Z
+date: 2022-08-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: glob
@@ -173,12 +173,11 @@ files:
 - CONTRIBUTING.md
 - Gemfile
 - LICENSE.md
+- MIGRATING_FROM_V3_TO_V4.md
 - README.md
 - Rakefile
 - exe/i18n
 - i18n-js.gemspec
-- i18njs.png
-- images/i18njs-check.gif
 - lib/guard/i18n-js.rb
 - lib/guard/i18n-js/templates/Guardfile
 - lib/guard/i18n-js/version.rb
@@ -200,10 +199,10 @@ metadata:
   rubygems_mfa_required: 'true'
   homepage_uri: https://github.com/fnando/i18n-js
   bug_tracker_uri: https://github.com/fnando/i18n-js/issues
-  source_code_uri: https://github.com/fnando/i18n-js/tree/v4.0.0.alpha4
-  changelog_uri: https://github.com/fnando/i18n-js/tree/v4.0.0.alpha4/CHANGELOG.md
-  documentation_uri: https://github.com/fnando/i18n-js/tree/v4.0.0.alpha4/README.md
-  license_uri: https://github.com/fnando/i18n-js/tree/v4.0.0.alpha4/LICENSE.md
+  source_code_uri: https://github.com/fnando/i18n-js/tree/v4.0.1
+  changelog_uri: https://github.com/fnando/i18n-js/tree/v4.0.1/CHANGELOG.md
+  documentation_uri: https://github.com/fnando/i18n-js/tree/v4.0.1/README.md
+  license_uri: https://github.com/fnando/i18n-js/tree/v4.0.1/LICENSE.md
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -215,9 +214,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 2.6.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubygems_version: 3.3.7
 signing_key: