# TranslateGettext

Extends \BaseParamFilterReader Implements \ChainableReader

Replaces gettext("message id") and _("message id") with the translated string.

Gettext is great for creating multi-lingual sites, but in some cases (e.g. for performance reasons) you may wish to replace the gettext calls with the translations of the strings; that's what this task is for. Note that this is similar to ReplaceTokens, but both the find and the replace aspect is more complicated -- hence this is a separate, stand-alone filter.

Example:

author | Hans Lellelid hans@xmpl.org
version | $Id: ceb6f10071ec525cd89b9f6dba2564971aa67a72 $
see |
package | phing.filters

### Methods

## __construct

    __construct(\Reader $in = null)

inherited

### Arguments

#### $in

`\Reader`

## Parses the parameters if this filter is being used in "generic" mode.

    _initialize()

## Creates a new TranslateGettext filter using the passed in Reader for instantiation.

    chain(\Reader $reader) : \TranslateGettext

### Arguments

#### $reader

`\Reader`

A Reader object providing the underlying stream. Must not be `null`.

### Response

`\TranslateGettext`

A new filter based on this configuration, but filtering the specified reader

## Make sure that required attributes are set.

    checkAttributes()

throws | if any required attribs aren't set.

## Close stream.

    close()

inherited abstract

throws | if there is an error closing stream

## Returns whether the end of file has been reached with input stream.

    eof() : boolean

inherited

### Response

`boolean`

## Gets the root locale directory.

    getDir() : \PhingFile

### Response

`\PhingFile`

## Get the current domain.

    getDomain() : string

### Response

`string`

## Returns the initialized status.

    getInitialized() : boolean

inherited

### Response

`boolean`

whether or not the filter is initialized

## Gets the locale to use for translation.

    getLocale() : string

### Response

`string`

## Returns the parameters to be used by this filter.

    getParameters() : array

inherited

### Response

`array`

the parameters to be used by this filter

## Returns the project this filter is part of.

    getProject() : object

inherited

### Response

`object`

The project this filter is part of

## Returns the filename, url, etc. that is being read from.

    getResource() : string

inherited abstract

This is critical for, e.g., ExpatParser's ability to know the filename that is throwing an ExpatParserException, etc.

### Response

`string`

## Initialize the gettext/locale environment.

    initEnvironment() : void

This method will change some env vars and locale settings; the restoreEnvironment should put them all back :)

throws | if locale cannot be set.
see | \TranslateGettext::restoreEnvironment()

## Convenience method to support logging in filters.

    log(string $msg, integer $level = \Project::MSG_INFO) : void

inherited

### Arguments

#### $msg

`string`

Message to log.

#### $level

`integer`

Priority level.

## If supported, places a "marker" (like a bookmark) at current stream position.

    mark()

inherited

A subsequent call to reset() will move stream position back to last marker (if supported).

## Whether marking is supported.

    markSupported() : boolean

inherited

### Response

`boolean`

## Read data from source.

    read(integer $len = null)

inherited abstract

If length is specified, then only that number of chars is read, otherwise stream is read until EOF.

### Arguments

#### $len

`integer`

## Reads a line of text ending with '\n' (or until the end of the stream).

    readLine() : string

inherited

The returned String retains the '\n'.

throws | if the underlying reader throws one during reading

### Response

`string`

the line read, or `null` if the end of the stream has already been reached

## Is stream ready for reading.

    ready() : boolean

inherited

### Response

`boolean`

## Reset the current position in stream to beginning or last mark (if supported).

    reset()

inherited

## Restores environment settings and locale.

    restoreEnvironment() : void

This does not restore any gettext-specific settings (e.g. textdomain()).

## Sets the root locale directory.

    setDir(\PhingFile $dir)

### Arguments

#### $dir

`\PhingFile`

## Set the text domain to use.

    setDomain(string $domain)

The text domain must correspond to the name of the compiled .mo files. E.g. "messages" ==> $dir/LC_MESSAGES/messages.mo "mydomain" ==> $dir/LC_MESSAGES/mydomain.mo

### Arguments

#### $domain

`string`

## Sets the initialized status.

    setInitialized(boolean $initialized)

inherited

### Arguments

#### $initialized

`boolean`

Whether or not the filter is initialized.

## Sets the locale to use for translation.

    setLocale(string $locale)

Note that for gettext() to work, you have to make sure this locale is specific enough for your system (e.g. some systems may allow an 'en' locale, but others will require 'en_US', etc.).

### Arguments

#### $locale

`string`

## Sets the parameters used by this filter, and sets the filter to an uninitialized status.

    setParameters(array $parameters) : void

inherited

throws |

### Arguments

#### $parameters

`array`

Array of parameters to be used by this filter. Should not be `null`.

## Sets the project to work with.

    setProject(object|\Project $project)

inherited

### Arguments

#### $project

`object|\Project`

The project this filter is part of. Should not be `null`.

## setReader

    setReader(\Reader $in)

inherited

### Arguments

#### $in

`\Reader`

## Move stream position relative to current pos.

    skip(integer $n)

inherited

### Arguments

#### $n

`integer`

## Performs gettext translation of msgid and returns translated text.

    xlateStringCallback(array $matches) : string

This function simply wraps gettext() call, but provides ability to log string replacements. (alternative would be using preg_replace with /e which would probably be faster, but no ability to debug/log.)

### Arguments

#### $matches

`array`

Array of matches; we're interested in $matches[2].

### Response

`string`

Translated text

### Constants

## DOMAIN_KEY

    DOMAIN_KEY

## DIR_KEY

    DIR_KEY

## LOCALE_KEY

    LOCALE_KEY

### Properties

## The domain to use

    domain :

### Type(s)

``

## The dir containing LC_MESSAGES

    dir :

### Type(s)

``

## The locale to use

    locale :

### Type(s)

``

## The system locale before it was changed for this filter.

    storedLocale :

### Type(s)

``

## The passed in parameter array.

    _parameters : array

inherited

var |

### Type(s)

`array`

## Have the parameters passed been interpreted?

    initialized :

inherited

### Type(s)

``

## The Phing project this filter is part of.

    project :

inherited

### Type(s)

``

## in

    in : \Reader

inherited

var |

### Type(s)

`\Reader`