opal-i18next 0.1.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0516e89ca4d90cf26eef7829ab80c86d67f8f05b0f1a8ef64e8c4cecefad15ae
-  data.tar.gz: 5c4504a1bedaa4da8fcd536d152d11bfa4f42accb6113d70d78451b395e8c27d
+  metadata.gz: 44c564b588879276f62325e8812dcab71272bffbd1c97e5cb122a0ef00039314
+  data.tar.gz: 0e588fd5cc1a8bc63d5060b52e862b9dbe7375f96673971eb421baca723aaf46
 SHA512:
-  metadata.gz: 9d492d66d45cd386d2a1fb90628bf77ee38af460325288c314e30d348eb362268b9f76e958e00c01d6568aec2f13d88edcff07ede09463360837cab5a3ab9914
-  data.tar.gz: ade7cf0f354a91b067c093a7e52a22fa0a47f34dc2855d73c4a7ebc13da085714958956e57ef18f8df07dedf0a06f32efa46ec86427cbb924aa537e248c67d26
+  metadata.gz: 76a08af7bd190a3538c98e47112a69cf183d6ec023b959af778e25f7b55effcaa64f34dbb0eff19de8dd674c3017b726c1b09ed92315f1f582d216eb337dd32d
+  data.tar.gz: c58800b3e827727ccac4ac8d001ca2444ff30e378ee38c1053edc8083f30b84af6cbd6f79b5d48eb6b8112c0a470423eb392d607dcf7d467fb06e4a94d6af578

data/.yardopts

@@ -0,0 +1 @@
+--no-private opal/i18next/**/*.rb

data/opal/i18next/i18next.rb

@@ -1,22 +1,51 @@
 require "opal"
 require "native"
+require "json"
 
-  # Uses PromiseV2 if present
-  # @see https://opalrb.com/docs/guides/v1.5.1/async PromiseV2
-  module I18next
+# Uses PromiseV2 if present
+# @see https://opalrb.com/docs/guides/v1.5.1/async PromiseV2
+module I18next
 
   Promise = defined?(PromiseV2) ? PromiseV2 : ::Promise
 
   # {I18next} is a basic wrapper around the JavaScript {https://www.i18next.com i18next module}.
   #
-  # It wraps i18next methods {https://www.i18next.com/overview/api#init init},
-  # {https://www.i18next.com/overview/api#use use},
-  # {https://www.i18next.com/overview/api#t t},
-  # {https://www.i18next.com/overview/api#changelanguage changeLanguage}, and
-  # {https://www.i18next.com/overview/api#language language}.
+  # It wraps i18next methods {https://www.i18next.com/overview/api#addResource addResource},
+  # {https://www.i18next.com/overview/api#addResourceBundle addResourceBundle},
+  # {https://www.i18next.com/overview/api#addResources addResources},
+  # {https://www.i18next.com/overview/api#changelanguage changeLanguage},
+  # {https://www.i18next.com/overview/api#dir dir},
+  # {https://www.i18next.com/overview/api#exists exists},
+  # {https://www.i18next.com/overview/api#getDataByLanguage getDataByLanguage},
+  # {https://www.i18next.com/overview/api#getFixedT getFixedT},
+  # {https://www.i18next.com/overview/api#getResource getResource},
+  # {https://www.i18next.com/overview/api#getResourceBundle getResourceBundle},
+  # {https://www.i18next.com/overview/api#hasResourceBundle hasResourceBundle},
+  # {https://www.i18next.com/overview/api#init init},
+  # {https://www.i18next.com/overview/api#language language},
+  # {https://www.i18next.com/overview/api#languages languages},
+  # {https://www.i18next.com/overview/api#loadLanguages loadLanguages},
+  # {https://www.i18next.com/overview/api#loadNamespaces loadNamespaces},
+  # {https://www.i18next.com/overview/api#events off},
+  # {https://www.i18next.com/overview/api#events on},
+  # {https://www.i18next.com/overview/api#removeResourceBundle removeResourceBundle},
+  # {https://www.i18next.com/overview/api#resolvedLanguage resolvedLanguage},
+  # {https://www.i18next.com/overview/api#setDefaultNamespace setDefaultNamespace},
+  # {https://www.i18next.com/overview/api#https://www.i18next.com/overview/api#store-events store.on},
+  # {https://www.i18next.com/overview/api#t t}, and
+  # {https://www.i18next.com/overview/api#use use}.
+  #
+  # It can handle {https://www.i18next.com/overview/api#events i18next events}. See methods on
+  # and off.
+  #
   # It also provides method {#import_js_module} for loading {https://www.i18next.com/overview/plugins-and-utils i18next plugins}.
   class I18next
 
+    # Each I18next instance has its own i18next Javascript module
+    def initialize
+      @i18next = `i18next.createInstance()`
+    end
+
     # Imports a JavaScript module (ESM)
     #
     # Use this method to import {https://www.i18next.com/overview/plugins-and-utils i18next JavaScript plugins}
@@ -43,17 +72,19 @@ require "native"
     #
     # @param js_module a plugin's JavaScript module that was imported
     #   by method {#import_js_module}
+    # @return [I18next::I18next] self
     def use(js_module)
-      `i18next.use(js_module.default)`
+      `#{@i18next}.use(js_module.default)`
+      self
     end
 
     # Initializes {https://www.i18next.com/overview/api#init i18next}
-    # @param options [Hash] a hash with keys matching the {https://www.i18next.com/overview/configuration-options i18next options}
+    # @param options [Hash] a hash with keys matching the {https://www.i18next.com/overview/configuration-options i18next options}.
     # @return [Promise] a promise that resolves when i18next has been initialized
-    def init(options)
+    def init(options = {})
       promise = Promise.new
       `
-      i18next.init(#{options.to_n})
+      #{@i18next}.init(#{options.to_n})
         .then(
           t => {
             promise.$resolve(t);
@@ -69,9 +100,9 @@ require "native"
     def change_language(language)
       promise = Promise.new
       `
-      i18next.changeLanguage(language).then(
-          t => {
-            promise.$resolve(t)
+      #{@i18next}.changeLanguage(language).then(
+          () => {
+            promise.$resolve()
           });
       `
       promise
@@ -79,14 +110,263 @@ require "native"
 
     # @return [String] the current {https://www.i18next.com/overview/api#language i18next} language
     def language
-      `i18next.language`
+      `#{@i18next}.language`
     end
 
     # The {https://www.i18next.com/overview/api#t i18next} translation associated with a key
-    # @param [String] key a key that references a translation, single key only
-    # @return [String] the translation associated with the key
-    def t(key)
-      `i18next.t(key)`
+    # @param [String, Array<String>] key one or more keys that reference translations
+    # @param [Hash] options options for formatters, post processors, etc.
+    # @return [String] the translation associated with the first key that resolves
+    def t(key, options={})
+      `#{@i18next}.t(key, #{options.to_n})`
+    end
+
+    # @return [Boolean] true if the key exists
+    def exists(key)
+      `#{@i18next}.exists(key)`
+    end
+
+    # Returns a Proc that acts a +t+ method that defaults to a language and namespace.
+    # @example When calling the returned Proc, use brackets, not parentheses
+    #   en = get_fixed_t("en")
+    #   translation = en["key"]
+    # @param lng [String] language
+    # @param ns [String] namespace
+    # @param key_prefix [String] key prefix
+    # @see https://www.i18next.com/overview/api#getFixedT The i18next getFixedT method
+    def get_fixed_t(lng = nil, ns = nil, key_prefix = nil)
+      if key_prefix && ns && lng
+        `#{@i18next}.getFixedT(lng, ns, key_prefix)`
+      elsif ns && lng
+        `#{@i18next}.getFixedT(lng, ns)`
+      elsif lng
+        `#{@i18next}.getFixedT(lng)`
+      else
+        `#{@i18next}.getFixedT()`
+      end
+    end
+
+    # @see https://www.i18next.com/overview/api#languages The i18next languages method
+    # @return language codes that will be used to look up the translation value
+    def languages
+      `#{@i18next}.languages`
+    end
+
+    # @see https://www.i18next.com/overview/api#resolvedLanguage The i18next resolvedLanguage method
+    # @return the current resolved language
+    def resolved_language
+      `#{@i18next}.resolvedLanguage`
+    end
+
+    # Loads additional namespaces not defined in init options
+    # @param ns [String, Array<String>] one or more namespaces
+    # @return [Promise] a promise that resolves when the namespaces have been loaded
+    # @see https://www.i18next.com/overview/api#loadNamespaces The i18next loadNamespaces method
+    def load_namespaces(ns)
+      promise = Promise.new
+      `
+      #{@i18next}.loadNamespaces(ns)
+        .then(
+          () => {
+            promise.$resolve()
+          });
+      `
+      promise
+    end
+
+    # Loads additional languages not defined in init options (preload).
+    # @param lngs [String, Array<String>] one or more languages
+    # @return [Promise] a promise that resolves when the languages have been loaded
+    # @see https://www.i18next.com/overview/api#loadLanguages The i18next loadLanguages method
+    def load_languages(lngs)
+      promise = Promise.new
+      `
+      #{@i18next}.loadLanguages(lngs)
+      .then(
+        () => {
+          promise.$resolve()
+        });
+    `
+      promise
+    end
+
+    # @private
+    def reload_resources
+      raise 'Not implemented'
+    end
+
+    # Changes the default namespace.
+    # @param ns [String] new default namespace
+    # @see https://www.i18next.com/overview/api#setDefaultNamespace The i18next setDefaultNamespace method
+    def set_default_namespace(ns)
+      `#{@i18next}.setDefaultNamespace(ns)`
+    end
+
+    # Get a language's reading direction
+    # @param lng [String] the language; if omitted, the current language is used
+    # @return "ltr" or "rtl"
+    # @see https://www.i18next.com/overview/api#dir The i18next dir method
+    def dir(lng)
+      `#{@i18next}.dir(lng)`
+    end
+
+    # @private
+    def format(data, format, lng)
+      raise 'Not implemented'
+    end
+
+    # @private
+    def create_instance(options)
+      raise 'Not implemented'
+    end
+
+    # @private
+    def clone_instance(options)
+      raise 'Not implemented'
+    end
+
+    # Gets one value by given key.
+    # @see https://www.i18next.com/overview/api#getResource The i18next getResource method
+    def get_resource(lng, ns, key, options = {})
+      `#{@i18next}.getResource(lng, ns, key, options)`
+    end
+
+    # Adds one key/value.
+    # @see https://www.i18next.com/overview/api#addResource The i18next addResource method
+    def add_resource(lng, ns, key, value, options = {})
+      `#{@i18next}.addResource(lng, ns, key, value, options)`
+    end
+
+    # Adds multiple key/values.
+    # @param resources [Hash] key/value pairs
+    # @see https://www.i18next.com/overview/api#addResources The i18next addResources method
+    def add_resources(lng, ns, resources)
+      `#{@i18next}.addResources(lng, ns, #{resources.to_n})`
+    end
+
+    # Adds a complete bundle
+    # @param lng [String] bundle language
+    # @param ns [String] bundel namespace
+    # @param deep [Boolean] if true will extend existing translations in the bundle
+    # @param overwrite [Boolean] if true it will overwrite existing translations in the bundle
+    # @see https://www.i18next.com/overview/api#addResourceBundle The i18next addResourceBundle method
+    def add_resource_bundle(lng, ns, resources, deep = false, overwrite = false)
+      `#{@i18next}.addResources(lng, ns, #{resources.to_n}, deep, overwrite)`
+    end
+
+    # Checks if a resource bundle exists
+    # @param lng [String] language
+    # @param ns [String] namespace
+    def has_resource_bundle(lng, ns)
+      `#{@i18next}.hasResourceBundle(lng, ns)`
+    end
+
+    # Returns resource data for a language.
+    # @param lng [String] language
+    # @return resource data
+    # @see https://www.i18next.com/overview/api#getDataByLanguage The i18next getDataByLanguage method
+    def get_data_by_language(lng)
+      js_obj_to_ruby_hash(`#{@i18next}.getDataByLanguage(lng)`)
+    end
+
+    # Gets a resource bundle.
+    # @return [Hash] key/value pairs
+    # @see https://www.i18next.com/overview/api#getResourceBundle The i18next getResourceBundle method
+    def get_resource_bundle(lng, ns)
+      js_obj_to_ruby_hash(`#{@i18next}.getResourceBundle(lng, ns)`)
+    end
+
+    # Removes a resource bundle exists
+    # @param lng [String] language
+    # @param ns [String] namespace
+    def remove_resource_bundle(lng, ns)
+      `#{@i18next}.removeResourceBundle(lng, ns)`
+    end
+
+    # Create a listener for an i18next event.
+    # @param event [String] event name
+    # @param &listener [block] an event listener that is passed event-dependent arguments
+    # @return [Proc] the listener, which can be used to unsubscribe it via method off(event, listener)
+    # @see https://www.i18next.com/overview/api#events The i18next events
+    # @see #off
+    def on(event, &listener)
+      # Some events require special listeners because those events return JavaScript objects
+      # to the listeners, and those object must be converted to Ruby Hashes.
+      case event
+      when "initialized"
+        _onInitialized(listener)
+      when "loaded"
+        _onLoaded(listener)
+      else
+        `#{@i18next}.on(event, listener)`
+      end
+      listener
+    end
+
+    # Create a listener for an i18next store event.
+    #
+    # Only available after the init call.
+    #
+    # @param event [String] event name ("added" or "removed")
+    # @param &listener [block] an event listener that is passed language and namespace arguments
+    # @return [Proc] the listener, which can be used to unsubscribe it via method off(event, listener)
+    # @see https://www.i18next.com/overview/api#store-events The i18next store events
+    def store_on(event, &listener)
+      `#{@i18next}.store.on(event, listener)`
+      listener
+    end
+
+    # Unsubscribes an event's listener(s)
+    # @param event [String] event name
+    # @param listener [Proc] the listener to unsubscribe; if absent, unsubscribe all listeners
+    def off(event, listener = nil)
+      if listener
+        `#{@i18next}.off(event, listener)`
+      else
+        `#{@i18next}.off(event)`
+      end
+    end
+
+    private
+
+    # @private
+    # Create a listener for the i18next initialized event.
+    # @param &listener [Proc] an event listener block that is passed initialized options Hash
+    # @see https://www.i18next.com/overview/api#oninitialized The i18next initialized event
+    def _onInitialized(listener)
+      `
+      #{@i18next}.on("initialized", (options) => {
+        // Convert the JavaScript options object to a string and
+        // then convert that string to a Ruby hash that is passed
+        // to the listener.
+        listener.$call(Opal.JSON.$parse(JSON.stringify(options)))
+      })
+      `
+    end
+
+    # @private
+    # Create a listener for the i18next loaded event.
+    # @param listener [Proc] an event listener block that is passed loaded Hash
+    # @see https://www.i18next.com/overview/api#onloaded The i18next onLoaded event
+    def _onLoaded(listener)
+      `
+      #{@i18next}.on("loaded", (loaded) => {
+        // Convert the JavaScript load object to a string and
+        // then convert that string to a Ruby hash that is passed
+        // to the listener.
+        listener.$call(Opal.JSON.$parse(JSON.stringify(loaded)))
+      })
+      `
+    end
+
+    # @private
+    # Convert a JavaScript obj to a Ruby Hash.
+    # @param js_obj JavaScript object
+    # @return [Hash] Ruby Hash
+    def js_obj_to_ruby_hash(js_obj)
+      # Convert the JavaScript object to a string and then convert that string
+      # to a Ruby hash.
+      JSON.parse(`JSON.stringify(js_obj)`)
     end
   end
 end

data/opal/i18next/version.rb

@@ -1,3 +1,3 @@
 module I18next
-  VERSION = '0.1.2'
+  VERSION = '0.3.0'
 end

data/opal-i18next.gemspec

@@ -6,8 +6,11 @@ Gem::Specification.new do |spec|
   spec.summary = "An Opal wrapper for the JavaScript i18next module."
   spec.description = <<~DESC
     A basic Opal wrapper for the JavaScript i18next module that supports methods
-    init, use, t, changeLanguage, and language. It also provides method
-    import_js_module for loading i18next plugins.
+    addResource, addResourceBundle, addResources, changeLanguage, dir, exists,
+    getDataByLanguage, getFixedT, getResource, getResourceBundle, hasResourceBundle,
+    init, language, languages, loadLanguages, loadNamespaces, off, on,
+    removeResourceBundle, resolvedLanguage, store.on, t, and use. It also
+    provides method import_js_module for loading i18next plugins.
   DESC
   spec.authors = ["Larry North"]
 
@@ -22,6 +25,7 @@ Gem::Specification.new do |spec|
   }
 
   spec.files += Dir["*.gemspec"]
+  spec.files += Dir[".yardopts"]
   spec.files += Dir["lib/**/*"]
   spec.files += Dir["opal/**/*"]
   spec.require_paths = ["lib"]

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: opal-i18next
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Larry North
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-08-24 00:00:00.000000000 Z
+date: 2022-09-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: opal
@@ -26,14 +26,18 @@ dependencies:
         version: 1.5.0
 description: |
   A basic Opal wrapper for the JavaScript i18next module that supports methods
-  init, use, t, changeLanguage, and language. It also provides method
-  import_js_module for loading i18next plugins.
+  addResource, addResourceBundle, addResources, changeLanguage, dir, exists,
+  getDataByLanguage, getFixedT, getResource, getResourceBundle, hasResourceBundle,
+  init, language, languages, loadLanguages, loadNamespaces, off, on,
+  removeResourceBundle, resolvedLanguage, store.on, t, and use. It also
+  provides method import_js_module for loading i18next plugins.
 email:
 - lnorth@swnorth.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".yardopts"
 - lib/opal-i18next.rb
 - lib/opal/i18next.rb
 - opal-i18next.gemspec