A site for Joomla! documentation

Joomla! Programmers Documentation

Manual Index

Using Text Class

To translate strings within your code, use the Text handling class from Joomla. The Text class contains six static main methods and one auxiliary method that can be used:

The key you pass to the ``Text::`` method must match a key defined in the corresponding language file or language override. 
MOD_EXAMPLE_HELLO="Hello"
MOD_EXAMPLE_GOODBYE="Goodbye"

Using Text::_

Searches for the defined language string in the current language file and outputs it. Displays the language constant in the frontend if no translation was found.

use Joomla\CMS\Language\Text;

// Usage in PHP code
echo Text::_("MOD_EXAMPLE_HELLO");  // Outputs: Hello

echo Text::_("MOD_EXAMPLE_GOODBYE");  // Outputs: Goodbye

Using Text::alt

Searches for the defined language string in the current language and outputs it. The $alt option defines where the translation has to be taken from. Displays the language constant in the frontend if no translation was found.

JALL="All"

JALL="All together"

use Joomla\CMS\Language\Text;

echo Text::alt('JALL', 'language'); // will generate a 'All' string in English but a "Toutes" string in French
echo Text::alt('JALL', 'module');   // will generate a 'All' string in English but a "Tous" string in French
By default, Joomla! always uses the language file supplied with the extension. It is then also possible to overwrite global language constants in this file. However, if the global constant is to be used at a certain point in the extension instead of the overwritten constant and its value, this can be achieved using the Text::alt method.

Using Text::plural

Automatic use of the correct language constant (pluralised) based on the transferred value.

use Joomla\CMS\Language\Text;

echo Text::plural('MOD_EXAMPLE_N_ITEMS_FOUND', 2);

MOD_EXAMPLE_N_ITEMS_FOUND="%d items found."
MOD_EXAMPLE_N_ITEMS_FOUND_0="No items found."
MOD_EXAMPLE_N_ITEMS_FOUND_1="Only one item found."
MOD_EXAMPLE_N_ITEMS_FOUND_2="Two items found."

Two items found.

A detailed explanation of the plural method can be found here.

Using Text::sprintf

Uses PHP's sprintf method in combination with translations to output a translated string. For example, variables can be used in a language string and formatted accordingly.

COM_EXAMPLE_MY_STRING="There's a lot of laundry in the %s."

use Joomla\CMS\Language\Text;

echo Text::sprintf("COM_EXAMPLE_MY_STRING", "laundry basket")

There's a lot of laundry in the laundry basket.

More examples of the use of sprintf can be found here.

If the `sprintf` method is called with too few arguments than expected, this leads to a fatal php error that is not intercepted by Joomla.

External Reference

Using Text::printf

Like the sprintf method, the printf method is a wrapper for the standard PHP printf function. The difference between printf and sprintf is that printf outputs the corresponding string directly, so no echo is required.

use Joomla\CMS\Language\Text;

Text::printf("COM_EXAMPLE_MY_STRING", "laundry basket")

There's a lot of laundry in the laundry basket.
If the `printf` method is called with too few arguments than expected, this leads to a fatal php error that is not intercepted by Joomla.

External Reference

Using Text::script

This method is necessary when you need multilingual strings in client-side JavaScript files. With Text::script, language strings can be passed to JavaScript in the frontend.

Typical use cases include:

  • Dynamic dialogs/popups (e.g., modal windows) that need to display user messages in the appropriate language.
  • Validation messages generated by JavaScript.
  • Any custom JavaScript components or UI interactions that rely on localized text.
COM_EXAMPLE_CONFIRM_DELETE="Are you sure you want to delete this item?"

use Joomla\CMS\Language\Text;

Text::script('COM_EXAMPLE_CONFIRM_DELETE');

// Retrieve the registered string in JavaScript
const deleteConfirmText = Joomla.Text._('COM_EXAMPLE_CONFIRM_DELETE');

// Use it in a dialog
alert(deleteConfirmText); // Displays: "Are you sure you want to delete this item?"
There is currently no direct way to use variables within the JavaScript translation, such as with `sprintf` for example. Instead, it is possible, to define placeholders within the translation which can then be replaced using JavaScript.

Using the Text::getScriptStrings Utility

The Text::getScriptStrings method in Joomla is a utility that allows you to retrieve an array of all the language strings that have been registered for JavaScript using the Text::script method. The main purpose of Text::getScriptStrings is to fetch all the strings that have been registered for use in JavaScript and make them accessible in an array format.

COM_EXAMPLE_CONFIRM_DELETE="Are you sure you want to delete this item?"
COM_EXAMPLE_SUCCESSFULLY_SAVED="The item was successfully saved."
COM_EXAMPLE_ACTION_FAILED="The action failed. Please try again."

use Joomla\CMS\Language\Text;

Text::script('COM_EXAMPLE_CONFIRM_DELETE');
Text::script('COM_EXAMPLE_SUCCESSFULLY_SAVED');
Text::script('COM_EXAMPLE_ACTION_FAILED');

$registeredStrings = Text::getScriptStrings();

// Output the array for debugging or custom processing
print_r($registeredStrings);

Array
(
    [COM_EXAMPLE_CONFIRM_DELETE] => "Are you sure you want to delete this item?"
    [COM_EXAMPLE_SUCCESSFULLY_SAVED] => "The item was successfully saved."
    [COM_EXAMPLE_ACTION_FAILED] => "The action failed. Please try again."
)