i18n-js 4.0.0 → 4.2.0

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,14 +12,14 @@
   <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>
 
 <p align="center">
   <a href="https://github.com/fnando/i18n-js"><img src="https://github.com/fnando/i18n-js/workflows/ruby-tests/badge.svg" alt="Tests"></a>
-  <a href="https://rubygems.org/gems/i18n-js"><img src="https://img.shields.io/gem/v/i18n-js.svg?include_prereleases" alt="Gem"></a>
+  <a href="https://rubygems.org/gems/i18n-js"><img src="https://img.shields.io/gem/v/i18n-js.svg" alt="Gem"></a>
   <a href="https://rubygems.org/gems/i18n-js"><img src="https://img.shields.io/gem/dt/i18n-js.svg" alt="Gem"></a>
   <a href="https://tldrlegal.com/license/mit-license"><img src="https://img.shields.io/:License-MIT-blue.svg" alt="MIT License"></a>
 </p>
@@ -45,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:
 
@@ -68,6 +76,22 @@ The output path can use the following placeholders:
 - `:locale`: the language that's being exported.
 - `:digest`: the MD5 hex digest of the exported file.
 
+The config file is processed as erb, so you can have dynamic content on it if
+you want. The following example shows how to use groups from a variable.
+
+```yml
+---
+<% group = "{en,pt}" %>
+
+translations:
+  - file: app/frontend/translations.json
+    patterns:
+      - "<%= group %>.*"
+      - "!<%= group %>.activerecord"
+      - "!<%= group %>.errors"
+      - "!<%= group %>.number.nth"
+```
+
 The Ruby API:
 
 ```ruby
@@ -88,7 +112,9 @@ Commands:
 - init: Initialize a project
 - export: Export translations as JSON files
 - version: Show package version
-- check: Check for missing translations
+- plugins: List plugins that will be activated
+- lint:translations: Check for missing translations
+- lint:scripts: Lint files using TypeScript
 
 Run `i18n COMMAND --help` for more information on specific commands.
 ```
@@ -97,14 +123,174 @@ By default, `i18n` will use `config/i18n.yml` and `config/environment.rb` as the
 configuration files. If you don't have these files, then you'll need to specify
 both `--config` and `--require`.
 
+### Plugins
+
+#### Built-in plugins:
+
+##### `embed_fallback_translations`:
+
+Embed fallback translations inferred from the default locale. This can be useful
+in cases where you have multiple large translation files and don't want to load
+the default locale together with the target locale.
+
+To use it, add the following to your configuration file:
+
+```yaml
+embed_fallback_translations:
+  enabled: true
+```
+
+##### `export_files`:
+
+By default, i18n-js will export only JSON files out of your translations. This
+plugin allows exporting other file formats. To use it, add the following to your
+configuration file:
+
+```yaml
+export_files:
+  enabled: true
+  files:
+    - template: path/to/template.erb
+      output: "%{dir}/%{base_name}.ts"
+```
+
+You can export multiple files by define more entries.
+
+The output name can use the following placeholders:
+
+- `%{dir}`: the directory where the translation file is.
+- `%{name}`: file name with extension.
+- `%{base_name}`: file name without extension.
+- `%{digest}`: MD5 hexdigest from the generated file.
+
+The template file must be a valid eRB template. You can execute arbitrary Ruby
+code, so be careful. An example of how you can generate a file can be seen
+below:
+
+```erb
+/* eslint-disable */
+<%= banner %>
+
+import { i18n } from "config/i18n";
+
+i18n.store(<%= JSON.pretty_generate(translations) %>);
+```
+
+This template is loading the instance from `config/i18n` and storing the
+translations that have been loaded. The
+`banner(comment: "// ", include_time: true)` method is built-in. The generated
+file will look something like this:
+
+```typescript
+/* eslint-disable */
+// File generated by i18n-js on 2022-12-10 15:37:00 +0000
+
+import { i18n } from "config/i18n";
+
+i18n.store({
+  en: {
+    "bunny rabbit adventure": "bunny rabbit adventure",
+    "hello sunshine!": "hello sunshine!",
+    "time for bed!": "time for bed!",
+  },
+  es: {
+    "bunny rabbit adventure": "conejito conejo aventura",
+    bye: "adios",
+    "time for bed!": "hora de acostarse!",
+  },
+  pt: {
+    "bunny rabbit adventure": "a aventura da coelhinha",
+    bye: "tchau",
+    "time for bed!": "hora de dormir!",
+  },
+});
+```
+
+#### Plugin API
+
+You can transform the exported translations by adding plugins. A plugin must
+inherit from `I18nJS::Plugin` and can have 4 class methods. To see a real
+example, see
+[lib/i18n-js/embed_fallback_translations_plugin.rb](https://github.com/fnando/i18n-js/blob/main/lib/i18n-js/embed_fallback_translations_plugin.rb)
+
+Here's the base `I18nJS::Plugin` class with the documented api:
+
+```ruby
+# frozen_string_literal: true
+
+module I18nJS
+  class Plugin
+    # This method is responsible for transforming the translations. The
+    # translations you'll receive may be already be filtered by other plugins
+    # and by the default filtering itself. If you need to access the original
+    # translations, use `I18nJS.translations`.
+    #
+    # Make sure you always check whether your plugin is active before
+    # transforming translations; otherwise, opting out transformation won't be
+    # possible.
+    def self.transform(translations:, config:)
+      translations
+    end
+
+    # In case your plugin accepts configuration, this is where you must validate
+    # the configuration, making sure only valid keys and type is provided.
+    # If the configuration contains invalid data, then you must raise an
+    # exception using something like
+    # `raise I18nJS::Schema::InvalidError, error_message`.
+    def self.validate_schema(config:)
+    end
+
+    # This method must set up the basic plugin configuration, like adding the
+    # config's root key in case your plugin accepts configuration (defined via
+    # the config file).
+    #
+    # If you don't add this key, the linter will prevent non-default keys from
+    # being added to the configuration file.
+    def self.setup
+    end
+
+    # This method is called whenever `I18nJS.call(**kwargs)` finishes exporting
+    # JSON files based on your configuration.
+    #
+    # You can use it to further process exported files, or generate new files
+    # based on the translations that have been exported.
+    #
+    # Make sure you always check whether your plugin is active before
+    # processing files; otherwise, opting out won't be possible.
+    def self.after_export(files:, config:)
+    end
+  end
+end
+```
+
+To distribute this plugin, you need to create a gem package that matches the
+pattern `i18n-js/*_plugin.rb`. You can test whether your plugin will be found by
+installing your gem, opening a iRB session and running
+`Gem.find_files("i18n-js/*_plugin.rb")`. If your plugin is not listed, then you
+need to double check your gem load path and see why the file is not being
+loaded.
+
 ### Listing missing translations
 
-To list missing and extraneous translations, you can use `i18n check`. This
-command will load your translations similarly to how `i18n export` does, but
-will output the list of keys that don't have a matching translation against the
-default locale. Here's an example:
+To list missing and extraneous translations, you can use
+`i18n lint:translations`. This command will load your translations similarly to
+how `i18n export` does, but will output the list of keys that don't have a
+matching translation against the default locale. Here's an example:
 
-![`i18n check` command in action](https://github.com/fnando/i18n-js/raw/main/images/i18njs-check.gif)
+```console
+$ i18n lint:translations
+=> Config file: "./config/i18n.yml"
+=> Require file: "./config/environment.rb"
+=> Check "./config/i18n.yml" for ignored keys.
+=> en: 232 translations
+=> pt-BR: 5 missing, 1 extraneous, 1 ignored
+   - pt-BR.actors.github.metrics (missing)
+   - pt-BR.actors.github.metrics_hint (missing)
+   - pt-BR.actors.github.repo_metrics (missing)
+   - pt-BR.actors.github.repository (missing)
+   - pt-BR.actors.github.user_metrics (missing)
+   - pt-BR.github.repository (extraneous)
+```
 
 This command will exist with status 1 whenever there are missing translations.
 This way you can use it as a CI linting.
@@ -125,19 +311,97 @@ translations:
     patterns:
       - "*"
 
-check:
+lint_translations:
   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.*`.
+> **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.*`.
+
+### Linting your JavaScript/TypeScript files
+
+To lint your script files and check for missing translations (which can signal
+that you're either using wrong scopes or forgot to add the translation), use
+`i18n lint:scripts`. This command will parse your JavaScript/TypeScript files
+and extract all scopes being used. This command requires a Node.js runtime. You
+can either specify one via `--node-path`, or let the plugin infer a binary from
+your `$PATH`.
+
+The comparison will be made against the export JSON files, which means it'll
+consider transformations performed by plugins (e.g. the output files may be
+affected by `embed_fallback_translations` plugin).
+
+The translations that will be extract must be called as one of the following
+ways:
+
+- `i18n.t(scope, options)`
+- `i18n.translate(scope, options)`
+- `t(scope, options)`
+
+Notice that only literal strings can be used, as in `i18n.t("message")`. If
+you're using dynamic scoping through variables (e.g.
+`const scope = "message"; i18n.t(scope)`), they will be skipped.
+
+```console
+$ i18n lint:scripts
+=> Config file: "./config/i18n.yml"
+=> Require file: "./config/environment.rb"
+=> Node: "/Users/fnando/.asdf/shims/node"
+=> Available locales: [:en, :es, :pt]
+=> Patterns: ["!(node_modules)/**/*.js", "!(node_modules)/**/*.ts", "!(node_modules)/**/*.jsx", "!(node_modules)/**/*.tsx"]
+=> 9 translations, 11 missing, 4 ignored
+   - test/scripts/lint/file.js:1:1: en.js.missing
+   - test/scripts/lint/file.js:1:1: es.js.missing
+   - test/scripts/lint/file.js:1:1: pt.js.missing
+   - test/scripts/lint/file.js:2:8: en.base.js.missing
+   - test/scripts/lint/file.js:2:8: es.base.js.missing
+   - test/scripts/lint/file.js:2:8: pt.base.js.missing
+   - test/scripts/lint/file.js:4:8: en.js.missing
+   - test/scripts/lint/file.js:4:8: es.js.missing
+   - test/scripts/lint/file.js:4:8: pt.js.missing
+   - test/scripts/lint/file.js:6:1: en.another_ignore_scope
+   - test/scripts/lint/file.js:6:1: es.another_ignore_scope
+```
+
+This command will list all locales and their missing translations. Avoid listing
+a particular translation, you can set `lint.ignore` on your config file.
+
+```yaml
+---
+translations:
+  - file: app/frontend/translations.json
+    patterns:
+      - "*"
+
+lint_scripts:
+  ignore:
+    - ignore_scope # will ignore this scope on all languages
+    - pt.another_ignore_scope # will ignore this scope only on `pt`
+```
+
+You can also set the patterns that will be looked up. By default, it scans all
+JavaScript and TypeScript files that don't live on `node_modules`.
+
+```yaml
+---
+translations:
+  - file: app/frontend/translations.json
+    patterns:
+      - "*"
+
+lint:
+  patterns:
+    - "app/assets/**/*.ts"
+```
 
 ## Automatically export translations
 
-### Using watchman
+### Using [watchman](https://facebook.github.io/watchman/)
 
 Create a script at `bin/i18n-watch`.
 
@@ -182,11 +446,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",
@@ -204,7 +468,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:
 
@@ -216,8 +480,25 @@ 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)
+- `run_on_start` - export files on start. Defaults to `true`. When disabled,
+  files will be exported only when there are file changes.
+
+Example:
+
+```ruby
+I18nJS.listen(
+  config_file: "config/i18n.yml",
+  locales_dir: ["config/locales", "app/views"],
+  options: {only: %r{.yml$}},
+  run_on_start: false
+)
+```
 
 ### Integrating with your frontend
 
@@ -227,6 +508,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
@@ -246,9 +534,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/bin/release

@@ -0,0 +1,81 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "../lib/i18n-js/version"
+
+def write_file(path, contents)
+  File.open(File.expand_path(path), "w") do |io|
+    io << contents
+  end
+end
+
+changelog_path = "./CHANGELOG.md"
+version_path = "./lib/i18n-js/version.rb"
+
+version = nil
+segments = I18nJS::VERSION.split(".")
+major, minor, patch = *segments.take(3).map(&:to_i)
+pre = segments[4].to_s
+pre_version = pre.gsub(/[^\d]/m, "").to_i
+date = Time.now.strftime("%b %d, %Y")
+dry_run = false
+alpha = false
+
+OptionParser.new do |opts|
+  opts.on("--major") do
+    version = "#{major + 1}.0.0"
+  end
+
+  opts.on("--minor") do
+    version = "#{major}.#{minor + 1}.0"
+  end
+
+  opts.on("--patch") do
+    version = "#{major}.#{minor}.#{patch + 1}"
+  end
+
+  opts.on("--alpha") do
+    alpha = true
+  end
+
+  opts.on("--dry-run") do
+    dry_run = true
+  end
+end.parse!
+
+version = "#{version}.alpha#{pre_version + 1}" if alpha
+
+unless version
+  puts "ERROR: You need to use either one of: --major, --minor, --patch"
+  exit 1
+end
+
+puts "=> Current version: #{I18nJS::VERSION}"
+puts "=> Next version: #{version}"
+
+system "yarn", "install"
+system "yarn", "compile"
+
+write_file changelog_path,
+           File.read(changelog_path)
+               .gsub("Unreleased", "v#{version} - #{date}")
+
+puts "=> Updated #{changelog_path}"
+
+write_file version_path,
+           File.read(version_path)
+               .gsub(/VERSION = ".*?"/, %[VERSION = "#{version}"])
+
+puts "=> Updated #{version_path}"
+
+unless dry_run
+  system "git", "add", changelog_path, version_path
+  system "git", "commit", "-m", "Bump up version (v#{version})"
+  system "rake", "release"
+end
+
+if dry_run
+  system "rake", "build"
+  system "git", "checkout", changelog_path, version_path
+end

data/i18n-js.gemspec

@@ -28,19 +28,22 @@ 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.files << "lib/i18n-js/lint.js"
+
   spec.bindir        = "exe"
   spec.executables   = spec.files.grep(%r{^exe/}) {|f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "glob"
+  spec.add_dependency "glob", ">= 0.4.0"
   spec.add_dependency "i18n"
 
   spec.add_development_dependency "activesupport"
   spec.add_development_dependency "minitest"
   spec.add_development_dependency "minitest-utils"
+  spec.add_development_dependency "mocha"
   spec.add_development_dependency "pry-meta"
   spec.add_development_dependency "rake"
   spec.add_development_dependency "rubocop"

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