rosette-core

Build Status Code Climate Test Coverage

Installation

gem install rosette-core

Usage

require 'rosette/core'

Intro

This repository contains the core classes for the Rosette internationalizaton framework. Full documentation can be found on rubydoc.info.

Generally, this library is required by other projects like rosette-server, which means that most likely you'll make use of it indirectly. Please refer to the documentation that accompanies these other projects to set up and use Rosette.

Major Components

What follows is a list of the major components in rosette-core. It's not meant to be an exhaustive list, but should give a decent overview of what's going on.

Commands

Rosette commands are designed to mimic git operations. For example, use the DiffCommand to show the added/removed/changed phrases between two git refs. Use the StatusCommand to compute the status of a git ref i.e. the percent translated per locale. Commands all follow the builder pattern, meaning you create a blank instance, call setter methods for required fields, then call the #execute method. Here's an example for the ShowCommand:

Rosette::Core::Commands::ShowCommand.new(rosette_config)
  .set_repo_name('my_awesome_repo')
  .set_ref('master')
  .execute

Git Classes

Rosette manages git repos by leveraging the open-source jGit library, which is a full git implementation for the JVM. The Repo and DiffFinder classes wrap jGit and provide a set of methods for interacting with git repositories in a slightly more Ruby-ish way. Specifically, Repo offers generic methods like #parents_of and #read_object_bytes, while DiffFinder finds diffs between git refs. Here's an example of creating a Repo instance and calculating a diff:

repo = Rosette::Core::Repo.from_path('/path/to/my_repo/.git')
repo.diff('master', 'my_branch')  # you can optionally specify a list of paths as well

Resolvers

The resolvers provide a way of looking up class constants for a number of Rosette's sub-components using slash-separated strings. For example, the ExtractorId class will resolve the string 'xml/android' into Rosette::Extractors::XmlExtractor::AndroidExtractor. Resolvers exist for extractors, integrations, pre-processors, and serializers.

Rosette::Core::ExtractorId.resolve('xml/android')
Rosette::Core::SerializerId.resolve('yaml/rails')

Snapshot Classes

Snapshots are Ruby hashes of file paths to git commit ids. The idea of the snapshot is central to Rosette's git model in that Rosette uses them to know when files that contain translatable content last changed. Rather than storing phrases for every file for every commit, Rosette only stores content when files change. Rosette can use a snapshot to gather a complete list of phrases for each commit in the repository.

You probably won't have to take snapshots manually, but if you do, here's an example:

Rosette::Core::SnapshotFactory.new
  .set_repo_config(repo_config)
  .set_start_commit_id('abc123')
  .set_paths('path/to/snapshot')  # looks at all paths in repo by default
  .take_snapshot

Queue Classes

You can choose to process new commits by placing them in a queue (perhaps in combination with a github webhook or a plain 'ol git hook). The queuing logic and various queue stages all live in rosette-core. The stages are:

  1. Fetch/pull the repo
  2. Extract phrases for the given commit, store in datastore
  3. Push phrases to TMS (translation management system) for translation
  4. Finalize the TMS submission (perform any necessary clean-up)

If you're not using a queue to process new commits, you'll have to process them some other way to stay current.

Interfaces

rosette-core contains a few base classes that serve as interfaces for implementations that live in other gems. For example, the rosette-extractor-yaml gem defines the YamlExtractor class, which inherits from Rosette::Core::Extractor. Other interfaces include Rosette::Tms::Repository, Rosette::Serializers::Serializer, Rosette::Preprocessors::Preprocessor, and more.

Requirements

All Rosette components only run under jRuby. Java dependencies are managed via the expert gem. Run bundle exec expert install to install Java dependencies.

Running Tests

bundle, then bundle exec expert install, then bundle exec rspec.

Authors