Language Laravel Package

Text

The Text class is the Language package's translation interface and is used for translating language keys to a requested language. Instantiating the Text class requires a Language instance to be injected.

Instantiating Text

There are several ways to instantiate a Text object. The class can be instantiated directly, created via Language::getText(), or a shared instance may be retrieved from a Joomla\DI\Container.

Example 1: Creating a Text Object

use Joomla\Language\Language;
use Joomla\Language\Text;

$language = new Language('/var/www/jfw-application', 'en-GB');
$text     = new Text($language);

Example 2: Loading a Text Object from a Language instance

use Joomla\Language\Language;

$language = new Language('/var/www/jfw-application', 'en-GB');
$text     = $language->getText();

Example 3: Loading a Text Object from the DI Container

Note: In order to use this method, your project must utilise Joomla's Dependency Injection package. A LanguageFactory object must also be stored in the container.

use Joomla\DI\Container;
use Joomla\Language\Service\LanguageFactoryProvider;

$container = new Container;
$container->registerServiceProvider(new LanguageFactoryProvider);

$languageFactory = $container->get('Joomla\Language\LanguageFactory');
$languageFactory->setLanguageDirectory('/var/www/jfw-application');

// This will also create a Language instance in the LanguageFactory in the default language
$text = $languageFactory->getText();

Translating a Key

The translate method is used for basic translations of language keys. The method requires the key to be supplied for translation and also has several optional parameters.

/*
 * [@param](https://github.com/param)   string   $string                The string to translate.
 * [@param](https://github.com/param)   array    $parameters            Array of parameters for the string
 * [@param](https://github.com/param)   array    $jsSafe                Array containing data to make the string safe for JavaScript output
 * [@param](https://github.com/param)   boolean  $interpretBackSlashes  To interpret backslashes (\\=\, \n=carriage return, \t=tabulation)
 */
public function translate($string, $parameters = array(), $jsSafe = array(), $interpretBackSlashes = true)

The following example demonstrates basic usage of the Text class.

use Joomla\Language\Language;
use Joomla\Language\Text;

$language = new Language('/var/www/jfw-application', 'en-GB');
$text     = new Text($language);

$translatedString = $text->translate('MY_KEY');

If the supplied key is found in the Language class storage, the translated string will be returned; otherwise the key will be returned.

Named Parameter Support

A new feature in 2.0 is support for named parameters. The second parameter in the translate method accepts an associative array where the key is the string to replace and the value is the replacement.

Assuming the following is the contents of the en-GB.ini language file:

MY_KEY="%term% Rocks!"

The following example demonstrates usage of the translate method with named parameters.

use Joomla\Language\Language;
use Joomla\Language\Text;

$language = new Language('/var/www/jfw-application', 'en-GB');
$text     = new Text($language);

// Will return "Joomla Rocks!"
$translatedAltString = $text->translate('MY_KEY', array('%term%' => 'Joomla');

Alternate Translations

The alt method is used for creating potential alternate translations of a base language key by specifying a possible suffix for the language key. If a language key with the specified suffix is found, the translated string for this key is returned, otherwise the base language key will be processed for translation.

/*
 * [@param](https://github.com/param)   string   $string                The string to translate.
 * [@param](https://github.com/param)   string   $alt                   The alternate option for global string
 * [@param](https://github.com/param)   array    $parameters            Array of parameters for the string
 * [@param](https://github.com/param)   array    $jsSafe                Array containing data to make the string safe for JavaScript output
 * [@param](https://github.com/param)   boolean  $interpretBackSlashes  To interpret backslashes (\\=\, \n=carriage return, \t=tabulation)
 */
public function alt($string, $parameters = array(), $alt, $jsSafe = false, $interpretBackSlashes = true)

Assuming the following is the contents of the en-GB.ini language file:

MY_KEY="Foo"
MY_KEY_ROCKS="Bar"

The following example demonstrates usage of the alt method.

use Joomla\Language\Language;
use Joomla\Language\Text;

$language = new Language('/var/www/jfw-application', 'en-GB');
$text     = new Text($language);

// Will return "Bar"
$translatedAltString = $text->alt('MY_KEY', 'ROCKS');

// Will return "Foo"
$translatedBaseString = $text->alt('MY_KEY', 'IS_COOL');

The alt method also supports named parameters.