opal-i18next 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a608d9ba3fba9ee08cc35ee247cad22a5c89c9950232c7f9f70c73e588d6da9a
-  data.tar.gz: 8e82b9dadb4b73f55d5156ac1deccfe7c1b17f1c64abec548734c33f7b9c040b
+  metadata.gz: 7fcbdd82651c265dc9b07aad0f56ae5dc80b13562e69904c7083d75d297fafed
+  data.tar.gz: 31bc9a0cd604bdc2b911290fd3aa7659dde49782ef8f02f2dee0cbd5df3618f1
 SHA512:
-  metadata.gz: 904501d0d9ef54c0c23a011cb5326db007e06f5d6ae42880e778330ce68003e3b667a6d5c19b92a3be4ee95f9dcc7b1c147e4fd2e732208139038f0bb85ba74e
-  data.tar.gz: 7494d5183b943f29a92745405684c97569bff3309396f7abc9eebdf558185c0c616e3e68c6156d8866ba3f4be8cf1a4774a99d8d5c172242a4674152ac872240
+  metadata.gz: c81f84936adae8165b9519651d66ca0ffc84b472f1315793fd83157fa0c4bf3473760cef76fd500873544a52414de0cbbc0f09c5b423b8988b1078ba1e9bc0e4
+  data.tar.gz: 26dd77f60baf03f73791cf3dead57f98a5d8369b8ff60bda0e3c2ebe33767c188580469668b2a3fff08023d4337dfa4f01695053f1d7aacd47462b7704f2b9e4

data/opal/i18next/i18next.rb

@@ -2,30 +2,56 @@ 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}.
+  # {I18next} is a basic wrapper around the JavaScript I18N module {https://www.i18next.com i18next}.
   #
-  # It wraps i18next methods {https://www.i18next.com/overview/api#addResource addResource},
-  # {https://www.i18next.com/overview/api#addResources addResources},
+  # It wraps i18next functions {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#cloneinstance cloneInstance},
   # {https://www.i18next.com/overview/api#dir dir},
   # {https://www.i18next.com/overview/api#exists exists},
-  # {https://www.i18next.com/overview/api#getResource getResource},
-  # {https://www.i18next.com/overview/api#getResourceBundle getResourceBundle},
+  # {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#loadNamespaces loadNamespaces},
-  # {https://www.i18next.com/overview/api#resolvedLanguage resolvedLanguage},
-  # {https://www.i18next.com/overview/api#setDefaultNamespace setDefaultNamespace},
+  # {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#reloadresources reloadResources},
+  # {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#store-events store.on},
   # {https://www.i18next.com/overview/api#t t}, and
   # {https://www.i18next.com/overview/api#use use}.
-  # It also provides method {#import_js_module} for loading {https://www.i18next.com/overview/plugins-and-utils i18next plugins}.
+  #
+  # Function {https://www.i18next.com/overview/api#createinstance createInstance}
+  # is not supported because each I18next::I18next instance has its own
+  # JavaScript i18next module instance. To create a new instance use
+  # I18next::I18next.new.
+  #
+  # Function {https://www.i18next.com/overview/api#format format} is not supported
+  # because it is a legacy function that has been superseded by
+  # {https://www.i18next.com/translation-function/formatting built-in formatting
+  # functions}.
+  #
+  # 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
@@ -41,7 +67,7 @@ require "json"
     # @param module_path [String] the path to the module's *.js file, may be a
     #   file path or a URL
     #
-    # @return [Promise] a promise that resolves to the JavaScript module that can be passed
+    # @return [Promise] a promise that resolves to a JavaScript module that can be passed
     #  to the {#use} method
     #
     def import_js_module(module_path)
@@ -55,16 +81,19 @@ require "json"
       promise
     end
 
-    # Loads an {https://www.i18next.com/overview/api#use i18next} plugin
+    # Loads an {https://www.i18next.com/overview/plugins-and-utils i18next plugin}
     #
-    # @param js_module a plugin's JavaScript module that was imported
+    # @param js_module [Object] a plugin's JavaScript module that was imported
     #   by method {#import_js_module}
+    # @return [I18next::I18next] self
+    # @see https://www.i18next.com/overview/api#use The i18next use function
     def use(js_module)
       `#{@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 = {})
       promise = Promise.new
@@ -82,6 +111,7 @@ require "json"
     # @param language [String] the new language
     # @return [Promise] a promise that resolves when the language's
     #   translations have been loaded
+    # @see https://www.i18next.com/overview/api#changelanguage The i18next changeLanguage function
     def change_language(language)
       promise = Promise.new
       `
@@ -93,7 +123,8 @@ require "json"
       promise
     end
 
-    # @return [String] the current {https://www.i18next.com/overview/api#language i18next} language
+    # @return [String] the current language
+    # @see https://www.i18next.com/overview/api#language The i18next language function
     def language
       `#{@i18next}.language`
     end
@@ -102,36 +133,53 @@ require "json"
     # @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
+    # @see https://www.i18next.com/overview/api#t The i18next t function
     def t(key, options={})
       `#{@i18next}.t(key, #{options.to_n})`
     end
 
     # @return [Boolean] true if the key exists
+    # @see https://www.i18next.com/overview/api#exists The i18next exists function
     def exists(key)
       `#{@i18next}.exists(key)`
     end
 
-    # @private
-    def get_fixed_t
-      raise 'Not implemented'
+    # Returns a Proc that acts as 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 function
+    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
+    # @see https://www.i18next.com/overview/api#languages The i18next languages function
     # @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
+    # @see https://www.i18next.com/overview/api#resolvedlanguage The i18next resolvedLanguage function
     # @return the current resolved language
     def resolved_language
       `#{@i18next}.resolvedLanguage`
     end
 
     # Loads additional namespaces not defined in init options
-    # @param [String, Array<String>] ns one or more namespaces
+    # @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
+    # @see https://www.i18next.com/overview/api#loadnamespaces The i18next loadNamespaces function
     def load_namespaces(ns)
       promise = Promise.new
       `
@@ -144,19 +192,45 @@ require "json"
       promise
     end
 
-    # @private
-    def load_languages(*lngs)
-      raise 'Not implemented'
+    # 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 function
+    def load_languages(lngs)
+      promise = Promise.new
+      `
+      #{@i18next}.loadLanguages(lngs)
+      .then(
+        () => {
+          promise.$resolve()
+        });
+    `
+      promise
     end
 
-    # @private
-    def reload_resources
-      raise 'Not implemented'
+    # Reloads resources on given state.
+    #
+    # Optionally you can pass an array of languages and/or namespaces as params if
+    # you don't want to reload all.
+    # @param lng [String, Array<String>] one or more languages
+    # @param ns [String, Array<String>] one or more namespaces
+    # @return [Promise] a promise that resolves when the resources have been loaded
+    # @see https://www.i18next.com/overview/api#reloadresources The i18next reloadResources function
+    def reload_resources(lng = nil, ns = nil)
+      if !lng && !ns
+        reload_all_resources
+      elsif lng && !ns
+        reload_lng_resources(lng)
+      elsif !lng && ns
+        reload_ns_resources(ns)
+      else
+        reload_lng_ns_resources(lng, ns)
+      end
     end
 
     # Changes the default namespace.
     # @param ns [String] new default namespace
-    # @see https://www.i18next.com/overview/api#setDefaultNamespace The i18next setDefaultNamespace method
+    # @see https://www.i18next.com/overview/api#setdefaultnamespace The i18next setDefaultNamespace function
     def set_default_namespace(ns)
       `#{@i18next}.setDefaultNamespace(ns)`
     end
@@ -164,81 +238,232 @@ require "json"
     # 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
+    # @see https://www.i18next.com/overview/api#dir The i18next dir function
     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
-
-    # @private
-    def off
-      raise 'Not implemented'
-    end
-
-    # @private
-    def on
-      raise 'Not implemented'
-    end
-
     # Gets one value by given key.
-    # @see https://www.i18next.com/overview/api#getResource The i18next getResource method
+    # @param lng [String] language
+    # @param ns [String] namespace
+    # @param key_prefix [String] key prefix
+    # @param options [Hash] key separator and ignore JSON structure
+    # @see https://www.i18next.com/overview/api#getresource The i18next getResource function
     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
+    # @see https://www.i18next.com/overview/api#addresource The i18next addResource function
     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
+    # @see https://www.i18next.com/overview/api#addresources The i18next addResources function
     def add_resources(lng, ns, resources)
       `#{@i18next}.addResources(lng, ns, #{resources.to_n})`
     end
 
-    # @private
-    def add_resource_bundle(lng, ns, resouces, deep, overwrite)
-      raise 'Not implemented'
+    # Adds a complete bundle
+    # @param lng [String] bundle language
+    # @param ns [String] bundle 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 function
+    def add_resource_bundle(lng, ns, resources, deep = false, overwrite = false)
+      `#{@i18next}.addResources(lng, ns, #{resources.to_n}, deep, overwrite)`
     end
 
-    # @private
+    # Checks if a resource bundle exists
+    # @param lng [String] language
+    # @param ns [String] namespace
+    # @return [Boolean] true if the bundle exists
     def has_resource_bundle(lng, ns)
-      raise 'Not implemented'
+      `#{@i18next}.hasResourceBundle(lng, ns)`
     end
 
-    # @private
+    # Returns resource data for a language.
+    # @param lng [String] language
+    # @return [Hash] resource data
+    # @see https://www.i18next.com/overview/api#getbatabylanguage The i18next getDataByLanguage function
     def get_data_by_language(lng)
-      raise 'Not implemented'
+      js_obj_to_ruby_hash(`#{@i18next}.getDataByLanguage(lng)`)
     end
 
     # Gets a resource bundle.
+    # @param lng [String] language
+    # @param ns [String] namespace
     # @return [Hash] key/value pairs
-    # @see https://www.i18next.com/overview/api#getResourceBundle The i18next getResourceBundle method
+    # @see https://www.i18next.com/overview/api#getresourcebundle The i18next getResourceBundle function
     def get_resource_bundle(lng, ns)
-      JSON.parse(`JSON.stringify(#{@i18next}.getResourceBundle(lng, ns))`)
+      js_obj_to_ruby_hash(`#{@i18next}.getResourceBundle(lng, ns)`)
     end
 
-    # @private
+    # Removes a resource bundle exists
+    # @param lng [String] language
+    # @param ns [String] namespace
+    # @see https://www.i18next.com/overview/api#removeresourcebundle The i18next removeResourceBundle function
     def remove_resource_bundle(lng, ns)
-      raise 'Not implemented'
+      `#{@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] a 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 unsubscribed 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).
+    #
+    # Listeners are created by method {#on}.
+    # @param event [String] event name
+    # @param listener [Proc] the listener to unsubscribe; if absent, unsubscribe all listeners
+    # @see https://www.i18next.com/overview/api#events The i18next events
+    # @see #on
+    def off(event, listener = nil)
+      if listener
+        `#{@i18next}.off(event, listener)`
+      else
+        `#{@i18next}.off(event)`
+      end
+    end
+
+    # Creates a clone of the current instance.
+    #
+    # Shares store, plugins and initial configuration. Can be used to create an
+    # instance sharing storage but being independent on set language or default namespaces.
+    # @param options [Hash] a hash with keys matching the {https://www.i18next.com/overview/configuration-options i18next options}
+    # @return [I18next::I18next] a new instance
+    # @see https://www.i18next.com/overview/api#cloneinstance The i18next cloneInstance function
+    def clone_instance(options = {})
+      I18nextClone.new(@i18next, options)
+    end
+
+    private
+
+    # @private
+    class I18nextClone < I18next
+      def initialize(js_i18next, options)
+        @i18next = `#{js_i18next}.cloneInstance(#{options.to_n})`
+      end
+    end
+
+    # @private
+    def reload_all_resources
+      promise = Promise.new
+      `
+      #{@i18next}.reloadResources()
+      .then(
+        () => {
+          promise.$resolve()
+        });
+    `
+      promise
+    end
+
+    def reload_lng_resources(lng)
+      promise = Promise.new
+      `
+      #{@i18next}.reloadResources(lng)
+      .then(
+        () => {
+          promise.$resolve()
+        });
+    `
+      promise
+    end
+
+    def reload_ns_resources(ns)
+      promise = Promise.new
+      `
+      #{@i18next}.reloadResources(null, ns)
+      .then(
+        () => {
+          promise.$resolve()
+        });
+    `
+      promise
     end
 
+    def reload_lng_ns_resources(lng, ns)
+      promise = Promise.new
+      `
+      #{@i18next}.reloadResources(lng, ns)
+      .then(
+        () => {
+          promise.$resolve()
+        });
+    `
+      promise
+    end
+
+    # @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.2.0'
+  VERSION = '0.4.0'
 end

data/opal-i18next.gemspec

@@ -5,11 +5,12 @@ Gem::Specification.new do |spec|
   spec.version = I18next::VERSION
   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
-    addResource, addResources, changeLanguage, dir, exists, getResource,
-    getResourceBundle, init, language, languages, loadNamespaces, resolvedLanguage,
-    t, and use. It also provides method import_js_module for
-    loading i18next plugins.
+    A basic Opal wrapper for the JavaScript I18N module i18next that supports functions
+    addResource, addResourceBundle, addResources, changeLanguage, cloneInstance,
+    dir, exists, getDataByLanguage, getFixedT, getResource, getResourceBundle,
+    hasResourceBundle, init, language, languages, loadLanguages, loadNamespaces,
+    off, on, reloadResources, removeResourceBundle, resolvedLanguage, store.on,
+    t, and use. It also provides method import_js_module for loading i18next plugins.
   DESC
   spec.authors = ["Larry North"]
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: opal-i18next
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Larry North
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-08-31 00:00:00.000000000 Z
+date: 2022-09-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: opal
@@ -25,11 +25,12 @@ dependencies:
       - !ruby/object:Gem::Version
         version: 1.5.0
 description: |
-  A basic Opal wrapper for the JavaScript i18next module that supports methods
-  addResource, addResources, changeLanguage, dir, exists, getResource,
-  getResourceBundle, init, language, languages, loadNamespaces, resolvedLanguage,
-  t, and use. It also provides method import_js_module for
-  loading i18next plugins.
+  A basic Opal wrapper for the JavaScript I18N module i18next that supports functions
+  addResource, addResourceBundle, addResources, changeLanguage, cloneInstance,
+  dir, exists, getDataByLanguage, getFixedT, getResource, getResourceBundle,
+  hasResourceBundle, init, language, languages, loadLanguages, loadNamespaces,
+  off, on, reloadResources, removeResourceBundle, resolvedLanguage, store.on,
+  t, and use. It also provides method import_js_module for loading i18next plugins.
 email:
 - lnorth@swnorth.com
 executables: []