to_lang

to_lang is a Ruby library that adds language translation methods to strings and arrays, backed by the Google Translate API.

Installation

Simply run:

gem install to_lang

Usage

To use to_lang, require the library, then call ToLang.start with your Google Translate API key. At this point you will have access to all the new translation methods, which take the form to_language, where "language" is the language you wish to translate to.

Google Translate attempts to detect the source language, but you can specify it explicitly by calling methods in the form to_target_language_from_source_language, where "target language" is the language you are translating to and "source_language" is the language you are starting with. An inverted form with equivalent functionality, from_source_language_to_target_language is also available. These methods are generated dynamically and will not appear in a calls to String.instance_methods or Array.instance_methods until they have been called once. Strings and arrays will, however, respond_to? these methods prior to their dynamic definition.

The dynamic methods are simply syntactic sugar for String#translate and Array#translate, which you can use directly as well.

to_lang also comes with a command line utility for quick translations from the shell.

String Examples

Load and initialize to_lang:

require 'to_lang'

ToLang.start('YOUR_GOOGLE_TRANSLATE_API_KEY')

Translate some text to Spanish:

"Very cool gem!".to_spanish # => "Muy fresco joya!"

A case where the source language is ambiguous:

"a pie".to_spanish # => "a pie"
"a pie".to_spanish_from_english # => "un pastel"

Or equivalently:

"a pie".from_english_to_spanish # => "un pastel"

Using String#translate directly:

"hello world".translate('es') # => "hola mundo"
"a pie".translate('es', :from => 'en') # => "un pastel"

Array Examples

Arrays can be used to translate a batch of strings in a single method call and a single HTTP request. The exact same methods shown above work for arrays as well. For example, to translate an array of strings to Spanish:

["One", "Two", "Three"].to_spanish # => ["Uno", "Dos", "Tres"]

Debugging

translate also has the advantage of allowing you to get debug output for a translation. translate accepts a :debug option with three possible values: :request, :response, and :all. :request will cause the method to return a hash of the parameters that will be sent to the Google Translate API. :response will cause the method to return the full response from the API call as a hash. :all will cause the method to return a hash which contains both the request hash and the full response.

"hello world".translate('es', :debug => :request)
# => {:key=>"my_key", :q=>"hello world", :target=>"es"}

"hello world".translate('es', :debug => :response)
# => {"data"=>{"translations"=>[{"translatedText"=>"hola mundo", "detectedSourceLanguage"=>"en"}]}}

"hello world".translate('es', :debug => :all)
# => {:request=>{:key=>"my_key", :q=>"hello world", :target=>"es"},
#    :response=>{"data"=>{"translations"=>[{"translatedText"=>"hola mundo",
#    "detectedSourceLanguage"=>"en"}]}}}

Command Line Interface

The command line utility to_lang has the following interface:

to_lang [--key API_KEY] [--from SOURCE_LANGUAGE] --to DESTINATION_LANGUAGE STRING [STRING, ...]

to_lang accepts a space separated list of strings to translate. At least one string is required, as is the --to option, which accepts a language code (e.g. "es"). to_lang will attempt to load a Google Translate API key from the GOOGLE_TRANSLATE_API_KEY environment variable. If one is not available, it must be passed in from the command line with the --key option. For complete usage instructions, invoke the utility with the --help option.

Examples:

A simple translation with the key being passed in directly from the command line:

to_lang --key YOUR_GOOGLE_TRANSLATE_API_KEY --to es "hello world"
hola mundo

With the key in an environment variable and multiple strings:

to_lang --to es "hello world" "a pie"
hola mundo
a pie

Specifying the source language:

to_lang --from en --to es "hello world" "a pie"
hola mundo
un pastel

Supported Languages

to_lang adds the following methods to strings and arrays. Each of these methods can be called with an explicit source language by appending _from_source_language or prepending from_source_language_ to the method name.

• to_afrikaans
• to_albanian
• to_arabic
• to_belarusian
• to_bulgarian
• to_catalan
• to_simplified_chinese
• to_traditional_chinese
• to_croatian
• to_czech
• to_danish
• to_dutch
• to_english
• to_estonian
• to_filipino
• to_finnish
• to_french
• to_galician
• to_german
• to_greek
• to_haitian_creole
• to_hebrew
• to_hindi
• to_hungarian
• to_icelandic
• to_indonesian
• to_irish
• to_italian
• to_japanese
• to_latvian
• to_lithuanian
• to_macedonian
• to_malay
• to_maltese
• to_norwegian
• to_persian
• to_polish
• to_portuguese
• to_romanian
• to_russian
• to_serbian
• to_slovak
• to_slovenian
• to_spanish
• to_swahili
• to_swedish
• to_thai
• to_turkish
• to_ukrainian
• to_vietnamese
• to_welsh
• to_yiddish

Documentation

API documentation can be found at rubydoc.info.

Feedback and Contributions

Feedback is greatly appreciated. If you have any problems with to_lang, please open a new issue. Make sure you are using the latest version of the gem, or HEAD if you've cloned the Git repository directly. Please include debugging output from using the :debug option of translate, if relevant to your issue. If you'd like to fix bugs, add features, or improve the library in general, feel free to fork the project and send me a pull request with your changes.