slang-rb

The official Ruby client library for Slang℠ -- https://getslang.com/

Kick-ass translation and content management.

Getting Started

If you are using Bundler, add the Slang gem to your Gemfile:

gem "slang", "~> 0.34.0" # accept all 0.34.x releases

Then use Bundler to install:

bundle install

If you're not using Bundler, just install like any other gem:

gem install slang

Next, you'll want to visit GetSlang.com (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:

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:

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:

:hello.t                               # => "Hello"
"homepage.greeting".t(name: "Adrian")  # => "Welcome Adrian!"

This is equivalent to calling Slang.t directly, like this:

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=:

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.

`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.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:

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:

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:

Using :data_dir if passed to Slang.ify.
Checking the environment variable SLANG_DATA_DIR.
Detecting Rails, and creating slang_data under Rails.root.
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 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:

Using :env if passed to Slang.ify.
Checking the environment variable SLANG_ENV.
Detecting Rails, and using Rails.env.
Check if :developer_key is set, if so, assumes development.
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. 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-rb

Getting Started

Basic Usage

Ruby SDK API

Slang.ify(config={})

Slang.t(key, variable_hash={})

Slang.locale_code

Slang.locale_code=(locale_code)

Slang.locale_codes

Slang.logger

Slang.logger=(logger)

Slang.keys

Slang::VERSION (string constant)

Slang::SlangError (class)

Slang::Helpers (module)

String#t and Symbol#t (instance method)