# Translate Helper

Often web sites are available in several languages. To translate the content of a site you should simply use Zend Translate and to integrate `Zend Translate` within your view you should use the `Translate` View Helper.

In all following examples we are using the simple Array Translation Adapter. Of course you can also use any instance of `Zend_Translate` and also any subclasses of `Zend_Translate_Adapter`. There are several ways to initiate the `Translate` View Helper:

- Registered, through a previously registered instance in `Zend_Registry`

- Afterwards, through the fluent interface

- Directly, through initiating the class

A registered instance of `Zend_Translate` is the preferred usage for this helper. You can also select the locale to be used simply before you add the adapter to the registry.

We are speaking of locales instead of languages because a language also may contain a region. For example English is spoken in different dialects. There may be a translation for British and one for American English. Therefore, we say "locale" instead of "language."

## Registered instance

To use a registered instance just create an instance of `Zend_Translate` or `Zend_Translate_Adapter` and register it within `Zend_Registry` using `Zend_Translate` as its key.

    // our example adapter
    $adapter = new Zend_Translate('array', array('simple' => 'einfach'), 'de');
    Zend_Registry::set('Zend_Translate', $adapter);

    // within your view
    echo $this->translate('simple');
    // this returns 'einfach'

If you are more familiar with the fluent interface, then you can also create an instance within your view and initiate the helper afterwards.

## Within the view

To use the fluent interface, create an instance of `Zend_Translate` or `Zend_Translate_Adapter`, call the helper without a parameter, and call the `setTranslator()` method.

    // within your view
    $adapter = new Zend_Translate('array', array('simple' => 'einfach'), 'de');
    $this->translate()->setTranslator($adapter)->translate('simple');
    // this returns 'einfach'

If you are using the helper without `Zend_View` then you can also use it directly.

## Direct usage

    // our example adapter
    $adapter = new Zend_Translate('array', array('simple' => 'einfach'), 'de');

    // initiate the adapter
    $translate = new Zend_View_Helper_Translate($adapter);
    print $translate->translate('simple'); // this returns 'einfach'

You would use this way if you are not working with `Zend_View` and need to create translated output.

As already seen, the `translate()` method is used to return the translation. Just call it with the needed messageid of your translation adapter. But it can also replace parameters within the translation string. Therefore, it accepts variable parameters in two ways: either as a list of parameters, or as an array of parameters. As examples:

## Single parameter

To use a single parameter just add it to the method.

    // within your view
    $date = "Monday";
    $this->translate("Today is %1\$s", $date);
    // could return 'Heute ist Monday'

Keep in mind that if you are using parameters which are also text, you may also need to translate these parameters.

## List of parameters

Or use a list of parameters and add it to the method.

    // within your view
    $date = "Monday";
    $month = "April";
    $time = "11:20:55";
    $this->translate("Today is %1\$s in %2\$s. Actual time: %3\$s",
                     $date,
                     $month,
                     $time);
    // Could return 'Heute ist Monday in April. Aktuelle Zeit: 11:20:55'

## Array of parameters

Or use an array of parameters and add it to the method.

    // within your view
    $date = array("Monday", "April", "11:20:55");
    $this->translate("Today is %1\$s in %2\$s. Actual time: %3\$s", $date);
    // Could return 'Heute ist Monday in April. Aktuelle Zeit: 11:20:55'

Sometimes it is necessary to change the locale of the translation. This can be done either dynamically per translation or statically for all following translations. And you can use it with both a parameter list and an array of parameters. In both cases the locale must be given as the last single parameter.

## Change locale dynamically

    // within your view
    $date = array("Monday", "April", "11:20:55");
    $this->translate("Today is %1\$s in %2\$s. Actual time: %3\$s", $date, 'it');

This example returns the Italian translation for the messageid. But it will only be used once. The next translation will use the locale from the adapter. Normally you will set the desired locale within the translation adapter before you add it to the registry. But you can also set the locale from within the helper:

## Change locale statically

    // within your view
    $date = array("Monday", "April", "11:20:55");
    $this->translate()->setLocale('it');
    $this->translate("Today is %1\$s in %2\$s. Actual time: %3\$s", $date);

The above example sets `'it'` as the new default locale which will be used for all further translations.

Of course there is also a `getLocale()` method to get the currently set locale.

## Get the currently set locale

    // within your view
    $date = array("Monday", "April", "11:20:55");

    // returns 'de' as set default locale from our above examples
    $this->translate()->getLocale();

    $this->translate()->setLocale('it');
    $this->translate("Today is %1\$s in %2\$s. Actual time: %3\$s", $date);

    // returns 'it' as new set default locale
    $this->translate()->getLocale();