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."
)