slang 0.34.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a22deccd66088233b3e7c232af09e47f60fffa16
+  data.tar.gz: 0147bf242fb7c0f73019e4ae99990d7ac422b16e
+SHA512:
+  metadata.gz: 135700c2e7e3fec39a7a0a71a046e3ce9032086358da8d081f429624c7737154b9cbff3c9e5329cba010f185c05f76cee10f98e5cb440b487cd5e20a415f8068
+  data.tar.gz: 71ad3325e0facdab9ec32b99e1258fda08256814199983fe44e415b41df35a03ed39c6ff3de515346f1661c3a0667f8775a74deeda9242e7a0c5c26ab188dab5

data/.gitignore

@@ -0,0 +1,6 @@
+# See https://help.github.com/articles/ignoring-files for more about ignoring files.
+# use a global ignore for editor/OS files: git config --global core.excludesfile '~/.gitignore_global'
+
+log/
+pkg/
+slang_data/

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Slang Ruby Client Release Notes
+
+This project adheres to [Semantic Versioning](http://semver.org/). For any release 0.x, all releases 0.x.y will be
+backwards-compatible with non-breaking changes. Once we reach 1.0.0, all 1.x.y releases will be backwards-compatible
+with non-breaking changes to 1.0.0.
+
+## 0.34.0 (2015-05-14)
+
+* Initial release. (@sickp)

data/Gemfile

@@ -0,0 +1,8 @@
+source "https://rubygems.org"
+gemspec
+
+group :development do
+  gem "minitest"
+  gem "pry"
+  gem "yard"
+end

data/Gemfile.lock

@@ -0,0 +1,28 @@
+PATH
+  remote: .
+  specs:
+    slang (0.34.0)
+      oj (~> 2.12)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    coderay (1.1.0)
+    method_source (0.8.2)
+    minitest (5.6.1)
+    oj (2.12.7)
+    pry (0.10.1)
+      coderay (~> 1.1.0)
+      method_source (~> 0.8.1)
+      slop (~> 3.4)
+    slop (3.6.0)
+    yard (0.8.7.6)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  minitest
+  pry
+  slang!
+  yard

data/LICENSE.md

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2014-2015 Slang Tech Inc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,242 @@
+# slang-rb
+
+The official Ruby client library for [Slang℠][slang-home] -- https://getslang.com/
+
+Kick-ass translation and content management.
+
+
+## Getting Started
+
+If you are using Bundler, add the Slang gem to your `Gemfile`:
+
+```ruby
+gem "slang", "~> 0.34.0" # accept all 0.34.x releases
+```
+
+Then use Bundler to install:
+
+```sh
+bundle install
+```
+
+If you're not using Bundler, just install like any other gem:
+
+```sh
+gem install slang
+```
+
+Next, you'll want to visit [GetSlang.com][slang-home] (if you haven't already) to obtain a **project key** and a
+**developer key**. A project key uniquely identifies your project and its translations. It is safe to check
+`project_key` into your code base where any developer can see it. However, your developer key is unique to you and
+should be kept as a secret.
+
+
+## Basic Usage
+
+Slang must be initialized when your application starts, before any content can be retrieved. In Rails, you would create
+a `config/initializers/slang.rb` like:
+
+```ruby
+Slang.ify(project_key: "...")
+```
+
+At a minimum, you'll need to specify a `project_key`. For development mode, you'll need to make your `developer_key`
+available as well. We recommend setting the environment variable `SLANG_DEVELOPER_KEY` in `~/.bashrc`, for example:
+
+```sh
+export SLANG_DEVELOPER_KEY="..."
+```
+
+If you're a lone developer (or security schmecurity!), you can also pass it directly to the `Slang.ify` initialization
+method.
+
+After Slang is initialized, all cached/embedded content and translations are immediately available. Slang will also
+start a lightweight, background thread to periodically check for updates.
+
+Slang adds an instance method `#t` to Ruby's `String` and `Symbol` classes to provide some sweet syntactic sugar:
+
+```ruby
+:hello.t                               # => "Hello"
+"homepage.greeting".t(name: "Adrian")  # => "Welcome Adrian!"
+```
+
+This is equivalent to calling `Slang.t` directly, like this:
+
+```ruby
+Slang.t(:hello)                               # => "Hello"
+Slang.t("homepage.greeting", name: "Adrian")  # => "Welcome Adrian!"
+```
+
+If your content is available in different languages, set the appropriate locale code with `Slang.locale_code=`:
+
+```ruby
+Slang.locale_code = :de                     # in German (where available)
+"hello".t                                   # => "Hallo"
+"homepage.greeting".t(name: "Boris")        # => "Willkommen Boris!"
+```
+
+In Rails, the `#t` instance method is automatically added to all `ActionView` and `ActionController` instances as well.
+
+
+## Ruby SDK API
+
+Slang's Ruby SDK API is documented below. Please feel free to check out the internals (and suggest improvements), but
+do not depend on the implementation details in your code! They will most likely change as Slang evolves. If you stick
+to the public API, your code will not break, as this project adheres to [Semantic Versioning 2.0.0][semver-home].
+
+###### `Slang.ify(config={})`
+
+Initializes Slang with the given configuration hash (see the next section below). This must be called before any other
+methods, even if `config` is empty. Keys must be symbols, values must be strings.
+
+###### `Slang.t(key, variable_hash={})`
+
+Fetch the translation for the given key name. The second parameter is a hash mapping variable names to their values.
+This is only necessary if the given key requires variables for interpolation, pluralization, or gender rules. `key` and
+any variable names are converted to lowercase strings (and are thus treated case-insensitively). A variable's value
+must be convertible to a String.
+
+In *Development mode*, if `key` is not found, a placeholder string derived from the key name (and passed variables) is
+returned. The missing key is reported back to the Slang service in the background.
+
+In *Production mode*, if `key` is not found, a placeholder string of the form `{{locale_code:key}}` is returned to
+indicate this issue. Hopefully, with proper testing, this will never happen. But if your users complain about curly
+braces, that might be the reason. Fortunately, the easy fix is to add the translation and push a new snapshot from
+[GetSlang.com][slang-home].
+
+###### `Slang.locale_code`
+
+Returns the current locale code (i.e. language, language + region), a symbol.
+
+###### `Slang.locale_code=(locale_code)`
+
+Sets the locale code for the current Thread or Fiber. Converts to a symbol.
+
+###### `Slang.locale_codes`
+
+Returns an array of locale codes (symbols) available in the current snapshot.
+
+###### `Slang.logger`
+
+Returns the Slang logger (if set). If Rails is detected when Slang initializes, it will use `Rails.logger` by default.
+
+###### `Slang.logger=(logger)`
+
+Assign a Logger-like object for Slang logging.
+
+###### `Slang.keys`
+
+Returns an array of keys (strings) available in the current snapshot.
+
+###### `Slang::VERSION` (string constant)
+
+A string constant representing the current slang-rb version.
+
+###### `Slang::SlangError` (class)
+
+The base class for all Slang errors. This is only raised due to a configuration or initialization programming error,
+and should not be caught.
+
+###### `Slang::Helpers` (module)
+
+This mix-in module provides the methods `t`, `locale_code`, and `locale_code=`. You can extend your own module or class
+to create module/class methods. This is how the main Slang module does it:
+
+```ruby
+module Slang
+  extend Helpers # provides Slang.t, Slang.locale_code, Slang.locale_code=
+  ...
+end
+```
+
+Or, you can include this module in a class to get instance methods:
+
+```ruby
+class View
+  include Slang::Helpers # provides t, locale_code, locale_code=
+  ...
+end
+```
+
+*Note: if you are using Rails, this is automagically done for your controllers and views.*
+
+###### `String#t` and `Symbol#t` (instance method)
+
+The instance method `#t` is added to the `String` and `Symbol` classes. This is identical to calling `Slang.t` with
+the given string or symbol.
+
+
+## Slang.ify Configuration
+
+The Slang initialization method `Slang.ify` takes a configuration hash with symbolic keys for configuration options.
+
+| Configuration Key    | Description                                           |
+|:---------------------|:------------------------------------------------------|
+| `:data_dir`          | Slang data directory for state and snapshots.         |
+| `:developer_key`     | Unique developer key / secret  for development mode.  |
+| `:embedded_snapshot` | Path to an embedded snapshot file.                    |
+| `:env`               | Environment, typically `production` or `development`. |
+| `:project_key`       | Unique project identifier.                            |
+
+##### `:data_dir`
+
+Slang's data directory should reside on permanent storage, as state information and cached snapshots (content /
+translations) should persist between application and server restarts. This directory can be safely shared across
+multiple worker processes on the same machine (possibly multiple machines if your NFS-Ninja is well-versed in the
+black arts). Do not check this directory into your version control system.
+
+Slang determines its data directory by:
+
+1. Using `:data_dir` if passed to `Slang.ify`.
+2. Checking the environment variable `SLANG_DATA_DIR`.
+3. Detecting Rails, and creating `slang_data` under `Rails.root`.
+4. Creating `slang_data` under the current work directory.
+
+##### `:developer_key`
+
+A developer key is a developer-specific secret that provides access-control and allows your application to run in
+*Development mode*. This value should not be checked into version control or disclosed to others. That said, developer
+keys can be invalidated and re-issued. Not that you would ever need that.
+
+If `:developer_key` is not specified explicitly, Slang checks if the environment variable `SLANG_DEVELOPER_KEY` is set.
+
+##### `:embedded_snapshot`
+
+Upon initialization, Slang will look for the latest cached snapshot in its data directory. If this is a fresh
+production deploy to a new machine, there may be none. In this case, it is useful to embed a snapshot in your release
+so that Slang has data immediately available. Otherwise, your users may see missing content/translations until the
+background update thread has a chance to pull down the latest snapshot (this typically takes only a second or two,
+which makes embedded snapshots less important in *Development mode*).
+
+If `:embedded_snapshot` is not specified explicitly, Slang checks if the environment variable `SLANG_EMBEDDED_SNAPSHOT`
+is set.
+
+##### `:env`
+
+Slang can run in either *Production mode* or *Development mode* (see [GetSlang.com][slang-home] for more details). If
+this value starts with `dev` (case-insensitive), Slang expects to start in *Developer mode* and requires a
+`developer_key`. For example, values of `development`, `dev`, `DEV` would run in *Development mode*, where as values of
+`production`, `prod`, or `staging` would run in *Production mode*.
+
+Slang determines its environment by:
+
+1. Using `:env` if passed to `Slang.ify`.
+2. Checking the environment variable `SLANG_ENV`.
+3. Detecting Rails, and using `Rails.env`.
+4. Check if `:developer_key` is set, if so, assumes `development`.
+5. Otherwise, assumes `production`.
+
+##### `:project_key`
+
+A project key is the unique identifier for your project. It is required.
+
+If `:project_key` is not specified explicitly, Slang expects the environment variable `SLANG_PROJECT_KEY` to be set.
+
+
+## Support
+
+You can find more detailed documentation on [GetSlang.com][slang-home]. If you cannot figure something out or think you
+have found a bug, let us know: support @ getslang.com. We're here to make this work. @sickp
+
+[slang-home]: https://getslang.com/
+[semver-home]: http://semver.org/

data/Rakefile

@@ -0,0 +1,12 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+end
+
+desc "Start console."
+task :console do
+  exec("pry", "-Ilib", "-rslang")
+end
+task default: :console

data/lib/slang.rb

@@ -0,0 +1,144 @@
+# slang-rb
+#
+# The official Ruby client library for Slang(sm). https://getslang.com/
+#
+# The MIT License (MIT)
+#
+# Copyright (c) 2014-2015 Slang Tech Inc
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy of
+# this software and associated documentation files (the "Software"), to deal in
+# the Software without restriction, including without limitation the rights to
+# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+# the Software, and to permit persons to whom the Software is furnished to do so,
+# subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+# IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#
+module Slang
+  class SlangError < StandardError; end
+
+  # Slang helpers module.
+  #
+  module Helpers
+
+    # Get the content / translation for the given key.
+    #
+    # In development mode, if a key is not found, a human-readable placeholder is returned (and the missing key is
+    # reported to the Slang service).
+    #
+    # In production mode, if a key is not found, a placeholder string of the form "{{locale_code:key}}" is returned.
+    #
+    # @param [#to_s] Key name, converted to a lowercase.
+    # @param [Hash{#to_s => #to_s}] variable hash (variable names to values)
+    # @return [String] translated string (frozen -- dup if mutation is necessary)
+    # @raise [SlangError] if not initialized.
+    #
+    def t(key, variable_hash={})
+      Slang.internal_translate(key, variable_hash)
+    end
+
+    # Returns the locale code for the current Thread or Fiber.
+    #
+    # @return [Symbol] locale code
+    #
+    def locale_code
+      Thread.current[:slang_locale_code] ||= :en
+    end
+
+    # Sets the current locale code (for the current Thread or Fiber).
+    #
+    # @param [#to_sym] locale code
+    #
+    def locale_code=(locale_code)
+      Thread.current[:slang_locale_code] = locale_code.to_sym
+    end
+
+  end
+
+  # Initialize Slang. This must be called first before any other methods.
+  #
+  # @param [Hash{Symbol => String}] configuration keys and values.
+  # @raise [SlangError] on initialization failure.
+  #
+  def self.ify(config={})
+    init(config)
+  end
+
+  # Return all the locale codes in the current snapshot.
+  #
+  # @return [Array<Symbol>] all locale codes in the current snapshot.
+  # @raise [SlangError] if not initialized.
+  #
+  def self.locale_codes
+    snapshot.locales.keys
+  end
+
+  # Return all the keys in the current snapshot.
+  #
+  # @return [Array<String>] all keys in the current snapshot.
+  # @raise [SlangError] if not initialized.
+  #
+  def self.keys
+    snapshot.keys
+  end
+
+  # Returns Slang's logger. If Rails is detected when Slang is initialized, this logger will default
+  # to Rails.logger.
+  #
+  # @returns [Logger, nil] current logger.
+  #
+  def self.logger
+    @logger
+  end
+
+  # Set the Logger-like instance Slang should use for logging.
+  #
+  # @param [Logger, nil] logger
+  #
+  def self.logger=(logger)
+    @logger = logger
+  end
+
+  extend Helpers # provides Slang.t, Slang.locale_code, Slang.locale_code=
+end
+
+# Experimental String extension.
+#
+class String
+
+  # Use this string instance as a key. See Slang.t for details.
+  #
+  # @param [Hash{#to_s => #to_s}] optional variable hash
+  # @return [String] translated string
+  # @raise [SlangError] if not initialized.
+  #
+  def t(variable_hash={})
+    Slang.internal_translate(self, variable_hash)
+  end
+end
+
+# Experimental Symbol extension.
+#
+class Symbol
+
+  # Use this symbol instance as a key. See Slang.t for details.
+  #
+  # @param [Hash{#to_s => #to_s}] optional variable hash
+  # @return [String] translated string
+  # @raise [SlangError] if not initialized.
+  #
+  def t(variable_hash={})
+    Slang.internal_translate(self, variable_hash)
+  end
+end
+
+require "slang/internal"