i18n-js 4.1.0 → 4.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 60f1ad0e9477d8e6570573f64ac2a55136653da8e4791c6fc32e69c9547e197b
-  data.tar.gz: d46a3d8b8a25020635d9c108b2cb2caf3a256e419112a21a0d986f94e1e19c37
+  metadata.gz: 6dac70b6202710a44a8303deff7206848d702b4cdb3cc926552aec41114ff745
+  data.tar.gz: 2631494d675d0d8459ab5450bb634fee6c305dd6c01d32bb03d647ac2a657d9e
 SHA512:
-  metadata.gz: a1d63d094866a836a69a9b3fc8f2989608a1b794daf5d5c82062e17b3bcb07ab7fb0ec8f2c05aa27a2585236cff33d974c313ca81be96de129340ecce8f78490
-  data.tar.gz: 7ec126b41663f765a421950c1ddcb215d460681355088fc77731673c44f3baf590cc58c6e5841bc9dda6f58732249488cdad3b020287b57d7d1de70cf8e95716
+  metadata.gz: 67c7b4a499d4848967461c1d3a798de2d814af972049f6977d7cf4dc5c6781bfc6ecdc1129068f963ba8dc115ebe5c219f078ef00b92204f86c54a114d55aba3
+  data.tar.gz: 329799184d84e27455783a6a4522b9a0cce446ba33ab3d5cfe74e22d08f685736abb4329e2506e1c2d83504d963c777317f8998a838fb3fae8c358f65569c5b5

data/CHANGELOG.md

@@ -11,6 +11,14 @@ Prefix your message with one of the following:
 - [Security] in case of vulnerabilities.
 -->
 
+## v4.2.0 - Dec 10, 2022
+
+- [Added] Add `I18nJS::Plugin.after_export(files:, config:)` method, that's
+  called whenever whenever I18nJS finishes exporting files. You can use it to
+  further process files, or generate new files based on the exported files.
+- [Added] Bult-in plugin `I18nJS::ExportFilesPlugin`, which allows exporting
+  files out of the translations file by using a custom template.
+
 ## v4.1.0 - Dec 09, 2022
 
 - [Added] Parse configuration files as erb.
@@ -18,6 +26,8 @@ Prefix your message with one of the following:
   exported during `I18n.listen`'s boot. The default value is `true`.
 - [Added] Now it's possible to transform translations before exporting them
   using a stable plugin api.
+- [Added] Built-in plugin `I18nJS::EmbedFallbackTranslationsPlugin`, which
+  allows embedding missing translations on exported files.
 - [Deprecated] The `i18n check` has been deprecated. Use
   `i18n lint:translations` instead.
 - [Added] Use `i18n lint:scripts` to lint JavaScript/TypeScript.

data/README.md

@@ -140,30 +140,96 @@ 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 3 class methods. The following
-example shows how the built-in `embed_fallback_translations` plugin is
-implemented.
+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
-  require "i18n-js/plugin"
-
-  class EmbedFallbackTranslationsPlugin < I18nJS::Plugin
-    CONFIG_KEY = :embed_fallback_translations
-
-    # 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).
+  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`.
     #
-    # If you don't add this key, the linter will prevent non-default keys from
-    # being added to the configuration file.
-    def self.setup
-      I18nJS::Schema.root_keys << CONFIG_KEY
+    # 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
@@ -172,59 +238,28 @@ module I18nJS
     # exception using something like
     # `raise I18nJS::Schema::InvalidError, error_message`.
     def self.validate_schema(config:)
-      return unless config.key?(CONFIG_KEY)
-
-      plugin_config = config[CONFIG_KEY]
-      valid_keys = %i[enabled]
-      schema = I18nJS::Schema.new(config)
+    end
 
-      schema.expect_required_keys(valid_keys, plugin_config)
-      schema.reject_extraneous_keys(valid_keys, plugin_config)
-      schema.expect_enabled_config(CONFIG_KEY, plugin_config[:enabled])
+    # 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 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`.
+    # 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
-    # transforming translations; otherwise, opting out transformation won't be
-    # possible.
-    def self.transform(translations:, config:)
-      return translations unless config.dig(CONFIG_KEY, :enabled)
-
-      translations_glob = Glob.new(translations)
-      translations_glob << "*"
-
-      mapping = translations.keys.each_with_object({}) do |locale, buffer|
-        buffer[locale] = Glob.new(translations[locale]).tap do |glob|
-          glob << "*"
-        end
-      end
-
-      default_locale = I18n.default_locale
-      default_locale_glob = mapping.delete(default_locale)
-      default_locale_paths = default_locale_glob.paths
-
-      mapping.each do |locale, glob|
-        missing_keys = default_locale_paths - glob.paths
-
-        missing_keys.each do |key|
-          components = key.split(".").map(&:to_sym)
-          fallback_translation = translations.dig(default_locale, *components)
-
-          next unless fallback_translation
-
-          translations_glob.set([locale, key].join("."), fallback_translation)
-        end
-      end
-
-      translations_glob.to_h
+    # processing files; otherwise, opting out won't be possible.
+    def self.after_export(files:, config:)
     end
   end
-
-  I18nJS.register_plugin(EmbedFallbackTranslationsPlugin)
 end
 ```
 
@@ -242,7 +277,20 @@ To list missing and extraneous translations, you can use
 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 lint:translations` 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.
@@ -300,9 +348,9 @@ you're using dynamic scoping through variables (e.g.
 `const scope = "message"; i18n.t(scope)`), they will be skipped.
 
 ```console
-$ i18n lint:scripts --config test/config/lint.yml --require test/config/require.rb
-=> Config file: "test/config/lint.yml"
-=> Require file: "test/config/require.rb"
+$ 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"]

data/bin/{pack → release}

@@ -19,7 +19,7 @@ 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")
-release = false
+dry_run = false
 alpha = false
 
 OptionParser.new do |opts|
@@ -39,8 +39,8 @@ OptionParser.new do |opts|
     alpha = true
   end
 
-  opts.on("--release") do
-    release = true
+  opts.on("--dry-run") do
+    dry_run = true
   end
 end.parse!
 
@@ -69,11 +69,13 @@ write_file version_path,
 
 puts "=> Updated #{version_path}"
 
-if release
+unless dry_run
   system "git", "add", changelog_path, version_path
   system "git", "commit", "-m", "Bump up version (v#{version})"
-  system "git", "tag", "v#{version}"
+  system "rake", "release"
 end
 
-system "rake", "build"
-system "git", "checkout", changelog_path, version_path unless release
+if dry_run
+  system "rake", "build"
+  system "git", "checkout", changelog_path, version_path
+end

data/lib/i18n-js/embed_fallback_translations_plugin.rb

@@ -6,21 +6,10 @@ module I18nJS
   class EmbedFallbackTranslationsPlugin < I18nJS::Plugin
     CONFIG_KEY = :embed_fallback_translations
 
-    # 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
       I18nJS::Schema.root_keys << CONFIG_KEY
     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:)
       return unless config.key?(CONFIG_KEY)
 
@@ -33,14 +22,6 @@ module I18nJS
       schema.expect_enabled_config(CONFIG_KEY, plugin_config[:enabled])
     end
 
-    # 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:)
       return translations unless config.dig(CONFIG_KEY, :enabled)
 

data/lib/i18n-js/export_files_plugin.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module I18nJS
+  require "i18n-js/plugin"
+
+  class ExportFilesPlugin < I18nJS::Plugin
+    CONFIG_KEY = :export_files
+
+    def self.setup
+      I18nJS::Schema.root_keys << CONFIG_KEY
+    end
+
+    def self.validate_schema(config:)
+      return unless config.key?(CONFIG_KEY)
+
+      plugin_config = config[CONFIG_KEY]
+      valid_keys = %i[enabled files]
+      schema = I18nJS::Schema.new(config)
+
+      schema.expect_required_keys(valid_keys, plugin_config)
+      schema.reject_extraneous_keys(valid_keys, plugin_config)
+      schema.expect_enabled_config(CONFIG_KEY, plugin_config[:enabled])
+      schema.expect_array_with_items(:files, plugin_config[:files])
+
+      plugin_config[:files].each do |exports|
+        schema.expect_required_keys(%i[template output], exports)
+        schema.reject_extraneous_keys(%i[template output], exports)
+        schema.expect_type(:template, exports[:template], String, exports)
+        schema.expect_type(:output, exports[:output], String, exports)
+      end
+    end
+
+    def self.after_export(files:, config:)
+      return unless config.dig(CONFIG_KEY, :enabled)
+
+      exports = config.dig(CONFIG_KEY, :files)
+
+      require "erb"
+      require "digest/md5"
+      require "json"
+
+      files.each do |file|
+        dir = File.dirname(file)
+        name = File.basename(file)
+        extension = File.extname(name)
+        base_name = File.basename(file, extension)
+
+        exports.each do |export|
+          translations = JSON.load_file(file)
+          template = Template.new(
+            file: file,
+            translations: translations,
+            template: export[:template]
+          )
+
+          contents = template.render
+
+          output = format(
+            export[:output],
+            dir: dir,
+            name: name,
+            extension: extension,
+            digest: Digest::MD5.hexdigest(contents),
+            base_name: base_name
+          )
+
+          File.open(output, "w") do |io|
+            io << contents
+          end
+        end
+      end
+    end
+
+    class Template
+      attr_accessor :file, :translations, :template
+
+      def initialize(**kwargs)
+        kwargs.each do |key, value|
+          public_send("#{key}=", value)
+        end
+      end
+
+      def banner(comment: "// ", include_time: true)
+        [
+          "#{comment}File generated by i18n-js",
+          include_time ? " on #{Time.now}" : nil
+        ].compact.join
+      end
+
+      def render
+        ERB.new(File.read(template)).result(binding)
+      end
+    end
+  end
+
+  I18nJS.register_plugin(ExportFilesPlugin)
+end

data/lib/i18n-js/plugin.rb

@@ -23,16 +23,44 @@ module I18nJS
   end
 
   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:) # rubocop:disable Lint/UnusedMethodArgument
       translations
     end
 
-    # Must raise I18nJS::SchemaInvalidError with the error message if schema
-    # validation has failed.
+    # 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

data/lib/i18n-js/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module I18nJS
-  VERSION = "4.1.0"
+  VERSION = "4.2.0"
 end

data/lib/i18n-js.rb

@@ -34,6 +34,10 @@ module I18nJS
       exported_files += export_group(group, config)
     end
 
+    plugins.each do |plugin|
+      plugin.after_export(files: exported_files.dup, config: config)
+    end
+
     exported_files
   end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: i18n-js
 version: !ruby/object:Gem::Version
-  version: 4.1.0
+  version: 4.2.0
 platform: ruby
 authors:
 - Nando Vieira
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-12-09 00:00:00.000000000 Z
+date: 2022-12-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: glob
@@ -190,7 +190,7 @@ files:
 - MIGRATING_FROM_V3_TO_V4.md
 - README.md
 - Rakefile
-- bin/pack
+- bin/release
 - exe/i18n
 - i18n-js.gemspec
 - lib/guard/i18n-js.rb
@@ -208,6 +208,7 @@ files:
 - lib/i18n-js/cli/ui.rb
 - lib/i18n-js/cli/version_command.rb
 - lib/i18n-js/embed_fallback_translations_plugin.rb
+- lib/i18n-js/export_files_plugin.rb
 - lib/i18n-js/lint.js
 - lib/i18n-js/lint.ts
 - lib/i18n-js/listen.rb
@@ -222,10 +223,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.1.0
-  changelog_uri: https://github.com/fnando/i18n-js/tree/v4.1.0/CHANGELOG.md
-  documentation_uri: https://github.com/fnando/i18n-js/tree/v4.1.0/README.md
-  license_uri: https://github.com/fnando/i18n-js/tree/v4.1.0/LICENSE.md
+  source_code_uri: https://github.com/fnando/i18n-js/tree/v4.2.0
+  changelog_uri: https://github.com/fnando/i18n-js/tree/v4.2.0/CHANGELOG.md
+  documentation_uri: https://github.com/fnando/i18n-js/tree/v4.2.0/README.md
+  license_uri: https://github.com/fnando/i18n-js/tree/v4.2.0/LICENSE.md
 post_install_message:
 rdoc_options: []
 require_paths: