The Rosette Platform

Repos and Extractors

In the previous section, I described how to configure a repository and add an extractor to it. Let’s go over each line in some detail.

First, we add a repository by calling the #add_repo method:

1

config.add_repo('my_awesome_repo') do |repo_config|

#add_repo yields a repo configuration object and takes a string argument that semantically identifies the repo. This repo name doesn’t really mean anything to Rosette - it’s only used to uniquely identify the repo. That said, it’s a good idea to use name of your repository here, since rosette-client will use it when making API calls. For example, if your repository is on disk at /path/to/my_awesome_repo, then you should use ‘my_awesome_repo’ as the repo name.

Next, we tell Rosette where to find the repo on disk and give it a semantic description:

1
2

repo_config.set_path('/path/to/workspace/my_awesome_repo/.git')
repo_config.set_description('A bowl of awesomeness')

Note that the path you specify should point to your repo’s .git directory.

Finally, we add an extractor to the repo. As described above, extractors are responsible for reading and parsing files that contain translatable content:

1
2
3
4
5

repo_config.add_extractor('yaml/rails') do |ext_config|
  ext_config.set_conditions do |cond|
    cond.match_path('config/locales/en.yml')
  end
end

In the same way #add_repo yields a repo configuration object, so does #add_extractor yield an extractor configuration object. Here we use the #set_conditions method to tell the extractor which files it should read and parse. Any of the files in the repository that match these conditions will have their phrases extracted and recorded in the configured datastore (for a full list of matchers, see rosette-core’s yard docs, specifically this).

You can chain matchers using #and and #or to build sets of complex matching rules. For example, if my Rails app also has an engine named ‘cart’ that has its own translations, I might configure the extractor like this:

1
2
3
4
5
6
7

repo_config.add_extractor('yaml/rails') do |ext_config|
  ext_config.set_conditions do |cond|
    cond.match_path('config/locales/en.yml').or(
      cond.match_path('cart/config/locales/en.yml')
    )
  end
end

Serializers and Pre-Processors

Extractors handle pulling strings out of your repository, but eventually you’ll need to write translations back out to files. That’s what serializers are for. Serializers handle the process of converting the translation entries in Rosette’s datastore to files your application can read and make use of. For a Rails app for example, we need to be able to serialize Spanish translations into the file at config/locales/es.yml.

Let’s configure a Rails yaml serializer for our repo:

1
2

require 'rosette/serializers/yaml-serializer'
repo_config.add_serializer('rails', format: 'yaml/rails')

That’s really all we have to do. Serializers optionally yield a serializer configuration object that we can use to configure pre-processors. Pre-processors modify translation text before it gets serialized and written. For example, I might want to normalize my translations using the Unicode normalization algorithm (in short, a process by which characters are “fixed” so they’re all consistently represented).

1
2
3
4

require 'rosette/preprocessors/normalization-preprocessor'
ser_config.add_preprocessor('normalization') do |pre_config|
  pre_config.set_normalization_form(:nfc)
end

Datastores and Caches

Up until this point, we haven’t configured a way for Rosette to store phrases and translations. To do so, we’ll go back to the top-level and add one using the #use_datastore method. Rosette expects the datastore to be implementation independent - in other words, Rosette doesn’t care how the datastore actually works under the hood. All that’s required is that the datastore conform to a well-defined datastore interface.

In our examples here, we’re going to use a datastore backed by ActiveRecord, the data access layer provided by Rails. Support for ActiveRecord comes in the form of the rosette-active-record gem, and we can configure it like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

require 'rosette/data_stores/active_record_data_store'
config.use_datastore(
  'active-record', {
    host: 'localhost',
    port: 3306,
    username: 'myname'
    password: 'secretsecret',
    adapter: 'jdbcmysql',
    database: 'rosette',
    encoding: 'utf8',
    pool: 16
  }
)

For this example, you’ll also need to add the activerecord-jdbcmysql-adapter gem to your gemfile. Since Rosette runs on top of JRuby, you’ll need to always use a JDBC-based adapter if you want to use rosette-active-record.

Next, let’s configure a cache. Configuring a cache can help Rosette’s performance. Under the hood, Rosette uses ActiveSupport::Cache, so you’ll need to choose one of the caches it supports. In this example, we’ll use memcached via the dalli gem:

1

config.use_cache(:dalli_store, namespace: 'whatever', compress: true)

Integrations

Integrations provide a mechanism for adding support for 3rd-party services to your Rosette configuration. For example, you may want to add an integration for the translation management system you’ve selected (like Transifex or Smartling). In our example, we’re going to show how to integrate with Rollbar, an error reporting service. We’d like to report extraction errors as well as anything else that might go wrong to help us track down and fix bugs:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

require 'rollbar'

notifier = Rollbar::Notifier.new.tap do |notifier|
  notifier.configure do |c|
    c.access_token = 'secretsecret'
    c.environment = 'production'
    c.logger = Rosette.logger
    c.enabled = true
  end
end

require 'rosette/integrations/rollbar_integration'

config.add_integration('rollbar') do |rollbar_config|
  rollbar_config.set_rollbar_notifier(notifier)
end

Now, any errors caught by Rosette will be sent to Rollbar.