NAME

I22r::Translate::Filter - Role for translation filters.

SYNOPSIS

To use a Filter on all translations

    I22r::Translate->config(
        filter => [  filter1, filter2, ... ],
        ... other config ...
    )

To use a Filter with a specific backend

    I22r::Translate->config(
        'My::Backend' => {
            filter => [  filter3, ... ],
            ... other backend config ...
        }
        ... other global config ...
    }

To use a Filter on a specific translation request

    I22r::Translate->translate_string(
        src => ..., dest => ..., text => ...,
        filter => [ filter4, ... ] );

(the filter option is also recognized with the I22r::Translate->translate_list or I22r::Translate->translate_hash methods.

DESCRIPTION

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. Classes that implement the I22r::Translate::Filter role can be used to adjust the text before it is passed to a translation engine, and to unadjust the translator's output.

METHODS

apply

$filter->apply( $request, $key )

Accepts a I22r::Translate::Request object and a key from the input. Sanitizes $req->text->{$key} for use in a translation backend and keeps a record of what modifications were made, so they can be unmade in the "unapply" method on the translator output.

unapply

$filter->unapply( $request, $key )

Modifies backend output in $req->results->{$key}->text to restore whatever changes were made to the backend input in the "apply" method.

DEVELOPMENT GUIDE

A new filter must implement the apply and unapply methods. The filter must track the modifications made to input in the apply method, including the correct order of modifications, so that those modifications may be undone in the correct order in the unapply method.

The source code for the I22r::Translate::Filter::Literal and I22r::Translate::Filter::HTML filters are currently the best places to look for examples of how this can be done.

SEE ALSO

I22r::Translate, I22r::Translate::Filter::Literal, I22r::Translate::Filter::HTML