Framework Documentation - Language Package

Overview

The Language package provides an interface for managing internationalisation support and translations within an application.
The base objects in the package, Language and Text are the primary classes used for configuring your application's
language data and translating language keys. Additionally, support for stemming
and transliteration is also available via the Stemmer and Transliterate classes.

Language Package Structure

A language package contains data to configure and customise the language handling and translations for a given language.
The base package requires the following files (note that xx-XX is used to represent a language code):

• xx-XX.ini - The base language strings for an application.
• xx-XX.localise.php - A localisation class to define language specific behaviours. This class must implement the LocaliseInterface.
• xx-XX.xml - The metadata for a language.

The base path to language packages must be specified when instantiating a Language instance. Language packages must be
stored in a language folder within this base path, and each language stored in a separate folder by langauge code. For example:

use Joomla\Language\Language;

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

This will create a Language instance for the en-GB language and specifies that the base folder path is /var/www/jfw-application.
Therefore, the XML metadata file should be stored to /var/www/jfw-application/language/en-GB/en-GB.xml.

Translating Language Keys

The Text class is responsible for translating language keys into a human friendly text string in the requested language.
Instantiating a Text class requires a Language instance is injected in the constructor. For convenience, a Text instance
can be retrieved via Language::getText(). More information about using the Text class can be found in the
class documentation.

Language Key Format

In order to be properly translated, language keys must match a specific format. Generally, a key must match the
#^[A-Z][A-Z0-9_\-\.]*\s* regex. Broken down, the first character of the key must be a letter, then any letter or number
are considered valid characters as well as an underscore (_), hyphen (-), or period (.). Only uppercase letters
are accepted. A language file can be debugged using the Language::debugFile() method. If debugFile() indicates there
are errors, the error list can be retrieved via Language::getErrorFiles().

use Joomla\Language\Language;

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

if (count($language->debugFile('/var/www/jfw-application/language/en-GB/en-GB.ini'))
{
	$errors = $language->getErrorFiles();

	// Application logic to display errors
}