Documentation Gem Version Build Status Code Climate

Translatomatic

Translates text files from one language to another, or from one format to another. The following file formats are currently supported:

File format Extensions
Properties .properties
Windows resource files .resw, .resx
Property lists (OSX plist) .plist
PO files .po, .pot
XCode strings .strings
YAML .yaml
Subtitles .srt, .ass, .ssa
HTML .html, .htm, .shtml
XML .xml
Markdown .md
Text files .txt
CSV files .csv

The following translation APIs can be used with Translatomatic:

Translated strings are saved in a database and reused.

Installation

Add this line to your application's Gemfile:

gem 'translatomatic'

And then execute:

$ bundle

Or install it yourself as:

$ gem install translatomatic

Usage

This gem provides an executable called translatomatic. The translatomatic command has a number of functions, not all of which are documented here. For help on available commands and options, execute:

$ translatomatic help

And for help on a command, execute:

$ translatomatic translate help
$ translatomatic translate help file

Setup

Check for available translation services and options with the services command:

$ translatomatic services

Options can be specified on the command line, in environment variables, or in translatomatic's configuration files. The configuration files can be modified using translatomatic's internal config command. To list all available configuration settings, use:

$ translatomatic config list
$ translatomatic config describe

Options can be set at the user level or the project level. See also the Configuration section below for more information.

Translating files

When translating files, translatomatic translates text one sentence or phrase at a time. If a file is re-translated, only sentences that have changed since the last translation are sent to the translator, and the rest are sourced from the local database.

To translate a Java properties file to German and French using the Google translator:

$ translatomatic translate file --translator Google strings.properties de,fr

This would create (or overwrite) strings_de.properties and strings_fr.properties with translated properties.

Displaying strings from a resource bundle

To read and display the store.description and store.name properties from local resource files in English, German, and French:

$ translatomatic display --locales=en,de,fr \
    resources/strings.properties store.description store.name

Extracting strings from source files

To extract strings from source files, use the strings command, e.g.

$ translatomatic strings file.rb

Converting files

Translatomatic can be used to convert files from one format to another. For example, to convert a Java properties file to an XCode strings file:

$ translatomatic convert strings.properties Localization.strings

Configuration

Translatomatic has a per-user configuration file at $HOME/.translatomatic/config.yml, and optionally a per project configuration file $PROJECT_DIR/.translatomatic/config.yml. The translatomatic config set command operates on the project level configuration when executed within a project containing a translatomatic configuration file. Otherwise the user level configuration file is changed. The --context option can be used to specify user or project level configuration. The effective value of a configuration option is determined by reading from the environment, the user level configuration file, the project level configuration file (if present), and from the command line. The last value found takes precedence over values read earlier.

Translatomatic configuration examples

To set google_api_key within the user configuration file, use:

$ translatomatic config set google_api_key value --context user

To set one or more translation services to use:

$ translatomatic config set translator Microsoft,Yandex

Secondary translators will only be used if a translation error occurs when using the first choice.

To set a default list of target locales:

$ translatomatic config set target_locales en,de,es,fr,it

With target_locales set, files can be translated without specifying target locales in the translate file command.

$ translatomatic translate file resources/strings.properties

To display the current configuration, execute

$ translatomatic config list

Database configuration

By default, translatomatic uses an sqlite3 database in $HOME/.translatomatic/translatomatic.sqlite3 to store translated strings. To store translations in a database, you should have an appropriate database adapter installed, such as the sqlite3 gem. Translatomatic does not install database adapters automatically. The database configuration can be changed by creating a database.yml file under $HOME/.translatomatic/database.yml for the production environment, e.g.

production:
  adapter: mysql2
  host: db.example.com
  database: translatomatic
  pool: 5
  encoding: utf8
  username: username
  password: password

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/smugglys/translatomatic. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting with the Translatomatic project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.