Skip to main content
Version: 5.3 (Upcoming)

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:

note

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.

Global
JALL="All"
Module Language File
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
info

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.

mod_example Template File Plural example
use Joomla\CMS\Language\Text;

echo Text::plural('MOD_EXAMPLE_N_ITEMS_FOUND', 2);
MOD_EXAMPLE Language File
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."
Result
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.

Language Strings containing Placeholder for variable
COM_EXAMPLE_MY_STRING="There's a lot of laundry in the %s."
Calling the translation and transferring a variable
use Joomla\CMS\Language\Text;

echo Text::sprintf("COM_EXAMPLE_MY_STRING", "laundry basket")
Result
There's a lot of laundry in the laundry basket.

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

danger

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.

Register the language string for JavaScript
use Joomla\CMS\Language\Text;

Text::printf("COM_EXAMPLE_MY_STRING", "laundry basket")
Result
There's a lot of laundry in the laundry basket.
danger

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.
Language File
COM_EXAMPLE_CONFIRM_DELETE="Are you sure you want to delete this item?"
Register the language string for JavaScript
use Joomla\CMS\Language\Text;

Text::script('COM_EXAMPLE_CONFIRM_DELETE');
Use the Language Constant in JavaScript
// 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?"
info

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.

Language File
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."
Registering multiple strings
use Joomla\CMS\Language\Text;

Text::script('COM_EXAMPLE_CONFIRM_DELETE');
Text::script('COM_EXAMPLE_SUCCESSFULLY_SAVED');
Text::script('COM_EXAMPLE_ACTION_FAILED');
Retrieve all the registered script strings
$registeredStrings = Text::getScriptStrings();

// Output the array for debugging or custom processing
print_r($registeredStrings);
Result
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."
)