Languages¶
Every string a plugin puts in front of a person — the subject line of the mail
plg_bookings_notify sends, the tab title a group plugin adds, the labels on
its own parameter form — comes from a translation file inside the plugin
directory. Putting them there is not only about translating: it is also what
lets a hub change your wording without editing your code.
Unlike modules, a plugin's language file is not loaded for you unless you ask. That one difference is the whole of this chapter's trap.
Where the files go¶
The directory is the language tag. The file name is the tag, a dot, and
plg_{group}_{name} — the same string used everywhere else the plugin is
identified.
The .sys.ini file holds only what the CMS needs before the plugin runs: the
name and description shown in the Plugin Manager. It is loaded by the
administrative interface, not by the plugin. Everything the plugin itself
renders belongs in the plain .ini. A plugin that renders nothing —
plg_content_formatwiki is one — ships only the .sys.ini.
Loading them¶
The base constructor loads nothing by default, because most plugins have no strings and loading a file per plugin per request would be wasted work. Opt in with a property:
With that set, the constructor calls loadLanguage() for you. You can also
call it yourself, later, from the one method that needs the strings — which is
the better choice for a plugin in a group that is imported on every request,
or one like plg_bookings_notify whose strings are needed on the rare request
that creates a reservation:
Warning
Forget both and nothing breaks loudly. Lang::txt() returns the
key it was given when there is no translation, so the mail goes out with
PLG_BOOKINGS_NOTIFY_SUBJECT as its subject line and the group tab is
labelled PLG_GROUPS_FORUM. A raw key in capitals on a page or in an email
means one of two things: the file was never loaded, or the key is not in it.
Where it looks¶
loadLanguage($extension = '', $basePath = PATH_APP) defaults $extension to
plg_{group}_{name} and then tries three locations, stopping at the first
that yields strings:
$basePath/language/{tag}/{tag}.plg_group_name.ini— the argument you passed.PATH_APPandPATH_COREare rewritten by the translator to{path}/bootstrap/{client}, the hub's own override directory.app/plugins/{group}/{name}/language/{tag}/…core/plugins/{group}/{name}/language/{tag}/…
The constructor's automatic call passes
PATH_APP/bootstrap/{client} explicitly, so the order is the same either way:
hub override, then app/, then core/.
Warning
Loading stops at the first file that parses. A hub override in
app/bootstrap/site/language/en-GB/ therefore replaces the plugin's file
rather than merging with it, and must contain every key the plugin uses.
The translator loads the site's default language before the requested one
unless debug_lang is on, so a key absent from a partial translation still
resolves through en-GB. Turning debug_lang on in the site configuration is
the fastest way to find keys that are not resolving: it stops that fallback,
wraps every string it did find in **, and every one it did not in ??.
Overriding the search¶
loadLanguage() is a normal method and a plugin may override it.
plgGroupsForum does, so that a super group can ship its own strings from
inside the group's own directory:
That is a super group feature, not a general pattern. A plugin that is not serving a group has no reason to override the search.
Writing the file¶
Keys are uppercase with underscores and start with PLG_{GROUP}_{NAME}_ so
they cannot collide with another extension's — the string table is one flat
namespace for the whole request, and the last file loaded wins. Values are
double-quoted; the files are parsed with parse_ini_file() in raw mode, so a
literal double quote inside a value is escaped as \". Comments start with a
semicolon.
Using a string¶
Lang::txt() passes extra arguments through sprintf, and returns the key
unchanged when there is no translation — which is why a missing string appears
on the page in capitals rather than as an error. A key with a %s in it and
no argument passed comes out with the %s still in it, for the same reason.
Note
The plugin entry class is in the root namespace, so Lang needs no
import there. A namespaced helper class beside the plugin is a different
case, and not the simple one: an unimported facade in a namespaced file
usually resolves anyway, through a fallback in the alias autoloader, and
then fails in a few specific situations. Import it. See
Facades, and run
php docs/_tools/lint/undefined-language-keys.php app/plugins/bookings/notify to
find keys with no string behind them.
Registering the file¶
List it in the manifest so the installer copies it:
See Languages for how the tag for a request is chosen and how further languages are installed.
Rewritten and checked against 2.4-main @ 91d03d0a23 on 2026-09-10.