/ 
I22r-Translate-0.95
River stage zero No dependents
/ I22r::Translate

NAME

I22r::Translate - Translate content with the Internationalizationizer

VERSION

Version 0.95

SYNOPSIS

use I22r::Translate;

I22r::Translate->config( ... );

$r = I22r::Translate->translate_string(
    src => 'en', dest => 'de', text => 'Good morning.' );

@r = I22r::Translate->translate_list(
    src => 'es', dest => 'en', 
    text => [ 'Buenos dias.', 'Tengo hambre.' ],
    filter => [ 'HTML' ]);

%r = I22r::Translate->translate_hash(
    src => 'en',
    dest => 'es',
    text => {
        field1 => 'hello world',
        field2 => 'How are you?'
    },
    timeout => 10 );

DESCRIPTION

I22r::Translate is a feature-ful, flexible, extensible framework for translating content between different languages.

You start by calling the package "config" method, where you set some global options and configure one or more I22r::Translate::Backend packages.

Pass text to be translated with the "translate_string", "translate_list", or "translate_hash" methods. These methods will choose an available backend class to perform the translation(s).

CONFIG

There are three levels of configuration that affect every translation request.

First, there is global configuration, set with this package's "config" method.

Second, there is configuration for each backend. This is also set with this package's "config" method, or with each backend package's config method.

Finally, there is configuration that can be set for each individual translation request.

Some configuration options are recognized at all three of these levels. Some other options may only be recognized by some of the backends (API keys, for example).

Some of the most commonly used configuration options are:

timeout => int

Stops processing the translation request if this many seconds have passed since the request / current backend was started. Only the completed translations will be returned. You can have a global timeout setting, a separate timeout for each backend, and a separate timeout for the current request.

callback => CODE

Specifies a code reference or a subroutine name that will be invoked when a new translation result is available.

The function will be called with two arguments: the request object that is handling the translation, and a hash reference containing the fields and values for the new translation result.

You can have separate callbacks in the global configuration, for each backend, and for the current request.

filter => ARRAY

Specifies one or more filters to apply to the translation input before text is passed to the backend(s). See "FILTERS", below, for more information. The global configuration, each backend configuration, and each request can specify different filters to use.

return_type => simple | object | hash

By default, return values (include the values from translate_hash) are simple scalars containing translated text, but supplying a return_type configuration parameter can instruct this module to return either a I22r::Translate::Result object or a hash reference for each translation result, either of which will provide access to additional data about the translation.

SUBROUTINES/METHODS

config

I22r::Translate->config( \%opts )

You must call the config method before you can use the I22r::Translate package. At least one of the options should be the name of a I22r::Translate::Backend with a hash reference of options to configure the backend. A minimal configuration call that uses the Google translation backend might look like:

I22r::Translate->config(
    'I22r::Translate::Google' => {
        ENABLED => 1,
        API_KEY => 'abcdefghijklmnopqrstuvwxyz0123456789',
        REFERER => 'http://mysite.com/'
    },
);

See the "CONFIG" section above for other common parameters to pass to the config method. See the documentation for each backend for the configuration parameters recognized and required for that backend.

translate_string

$text_in_lang2 = I22r::Translate->translate_string( src => lang1, dest => lang2, text => text in lang1, option => value, ...)

Attempt to translate the text in a single scalar from language lang1 to language lang2. The src, dest, and text arguments are required. Any other parameters are interpreted as configuration that applies to the translation. See the "CONFIG" section for some possible choices.

translate_list

@text_in_lang2 = I22r::Translate->translate_list( src => lang1, dest => lang2, text => [ text1, text2, ... ], option => value, ...)

Translate a list of text strings between languages lang1 and lang2, returning the translated list. The src and dest arguments are required, and the text argument must be an array reference. Other parameter are interpreted as configuration that applies to the current translation.

The output array will have the same number of elements as the text input. If any of the input string were not translated, some or all of the output elements may be undef.

For some backends, it may be much more efficient to translate a list of strings at once rather than to call translate_string repeatedly.

translate_hash

%text_in_lang2 = I22r::Translate->translate_hash( src => lang1, dest => lang2, text => [ text1, text2, ... ], option => value, ...)

Translate the text string values of a hash reference between languages lang1 and lang2, returning a hash with the same keys as the input and translated text as the values. The src and dest arguments are required, and the text argument must be a hash reference with arbitrary keys and values as text strings in lang1. Other parameter are interpreted as configuration that applies to the current translation.

The output will not contain key-value pairs for the some or all of the output elements may be undef.

FILTERS

Sometimes you do not want to pass a piece of text directly to a translation engine. The text might contain HTML tags or other markup. It might contain proper nouns or other words that you don't intend to translate.

The I22r::Translate::Filter provides a mechanism to adjust the text before it is passed to a translation engine and to unadjust the output from the translator.

The filter configuration parameter may be used in global configuration (the "config" method), backend configuration (also the "config" method), or in a translation request (the translate_XXX methods). The filter config value is an array reference of the filters to apply to translator input, in the order they are to be applied. You may either provide the name of the filter class (an implementor of the I22r::Translation::Filter role), an instance of a filter class, or a sinple string. In the latter case, I22r::Translate will attempt to convert it to the name of a filter class by prepending I22r::Translate::Filter:: to the string.

See I22r::Translate::Filter::Literal and I22r::Translate::Filter::HTML for examples of filters that are included with this distribution, and I22r::Translate::Filter for general information and instructions for creating your own filters.

AUTHOR

Marty O'Brien, <mob at cpan.org>

BUGS

Please report any bugs or feature requests to bug-i22r-translate at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=I22r-Translate. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc I22r::Translate

You can also look for information at:

SEE ALSO

Lingua::Translate

LICENSE AND COPYRIGHT

Copyright 2012-2013 Marty O'Brien.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.