I18n

MMO\core · 1 symbol · generated 30 Sep 2026

class

I18n

Internationalization module.

class MMO\core\I18n extends MMO\core\classes\aModule

Namespace: MMO\core
Extends: aModule

You should write all your message in the same language (English normally). Any dynamic text in a message should be written as a placeholder moustache (`{xxx}`). To translate a message, we use its md5 and look for a translation for this message in the required language.

Index

	LANGUAGE_REGEX
	dateMDY	Country that use notation month/day/year
	lang
	translations
	DefaultConfig() static
	findLanguage($lang, $languages, $useValues)	Find language in a list of languages
	formatDate($format, $date, $lang)	Format a date, then translate its textual parts (`translateDate`).
	get($text, $lang)	Look up a single translation, with no placeholder substitution (`translate` for that).
	getByPrefix($prefix, $lang)	Returns a list of translation with a given prefix, removing the prefix from the id
	isMDYFormat($lang)
	load($lang, $translations)	Register (merging into any already-loaded for the same language) a set of `message => translation` pairs.
	matchLanguage($range, $lang)	RFC 4647 §3.3.2, the exact matching algorithm, transcribed step by step:
	onInc($event)
	setLanguage($lang)	Set language.
	splitLanguage($lang)	Match the full input against the RFC 5646 §2.1 'langtag' production:
	translate($message, $context, $prefix, $lang)	Translate a message and its context
	translateDate($date, $lang)	Translate the textual parts of an already-formatted date (e.g.
	_($message, $context, $prefix, $lang) static	Main entry point to translate a string

Constants1

LANGUAGE_REGEX

const LANGUAGE_REGEX = '(?<language>[A-Za-z]{2,3}(?:-(?<extlang>[A-Za-z]{3}(?:-[A-Za-z]{3}){0,2}))?|[A-Za-z]{4}|[A-Za-z]{5,8})(?:-(?<script>[A-Za-z]{4}))?(?:-(?<region>[A-Za-z]{2}|[0-9]{3}))?(?:-(?<variants>(?:[A-Za-z0-9]{5,8}|[0-9][A-Za-z0-9]{3})(?:-(?:[A-Za-z0-9]{5,8}|[0-9][A-Za-z0-9]{3}))*))?(?:-(?<extensions>[A-WY-Za-wy-z0-9]-[A-Za-z0-9]{2,8}(?:-[A-Za-z0-9]{2,8})*(?:-[A-WY-Za-wy-z0-9]-[A-Za-z0-9]{2,8}(?:-[A-Za-z0-9]{2,8})*)*))?(?:-(?<privateuse>[xX](?:-[A-Za-z0-9]{1,8})+))?'

Properties3

dateMDY

Country that use notation month/day/year

array $dateMDY = […13 items]

Type: array

lang

#[MMO\core\attributes\Serialize(null, 'setLanguage')] protected string $lang = ''

Type: string

translations

protected array $translations = []

Type: array

Methods14

DefaultConfig()

staticI18n.php:42

static function DefaultConfig(): array

returns array default configuration: the current language defaults to the LANGUAGE constant.

findLanguage($lang, $languages, $useValues)

I18n.php:253

Find language in a list of languages

function findLanguage(string $lang, array $languages, bool $useValues = false): string|int|null

$lang	string	language tag
$languages	array	list or map of languages
$useValues = false	bool	if true, use values instead of keys for the lookup
returns	string \| int \| null	the key in $languages or null

formatDate($format, $date, $lang)

I18n.php:308

Format a date, then translate its textual parts (translateDate).

function formatDate( string $format = 'l d F Y', DateTimeInterface|string|int $date = 'now', ?string $lang = null )

$format = 'l d F Y'	string	a `DateTime::format` format string.
$date = 'now'	DateTimeInterface \| string \| int	`dateTime`.
$lang = null	null \| string
returns

$i18n->load('fr', ['/dates:Monday' => 'Lundi']); $i18n->formatDate('l', '2024-01-01', 'fr'); // 'Lundi'

get($text, $lang)

I18n.php:76

Look up a single translation, with no placeholder substitution (translate for that).

function get(string $text, ?string $lang = null): string

$text	string	the message to translate.
$lang = null	null \| string	defaults to the current language (`setLanguage`); resolved via `findLanguage` (so a close-enough loaded language, e.g. 'en' for a requested 'en-GB', is used if there's no exact match).
returns	string	the translation, or $text itself if none is found.

getByPrefix($prefix, $lang)

I18n.php:88

Returns a list of translation with a given prefix, removing the prefix from the id

function getByPrefix(string $prefix, ?string $lang = null): array

$prefix	string
$lang = null	null \| string
returns	array

isMDYFormat($lang)

I18n.php:283

function isMDYFormat(?string $lang = null): bool

$lang = null	null \| string
returns	bool	whether $lang (default: the current language) conventionally writes dates as month/day/year (`$dateMDY`).

load($lang, $translations)

I18n.php:64

function load(string $lang, array $translations): void

$lang	string	supports `_` and `-`.
$translations	array	message => translation.
returns	void

$i18n->load('fr', ['Hello' => 'Bonjour']);

matchLanguage($range, $lang)

I18n.php:203

RFC 4647 §3.3.2, the exact matching algorithm, transcribed step by step:

function matchLanguage(string $range, string $lang): bool

1. Split both the extended language range and the language tag into subtag lists (split on '-'). Two subtags match if they are equal case-insensitively, or the range's subtag is the wildcard '*'. 2. Compare the first subtag of each list. If they don't match, the overall match fails. Otherwise advance both pointers. 3. While there are more subtags left in the range's list: A. If the range's current subtag is '*', advance the range pointer only, and continue. B. Else if there are no more subtags in the tag's list, fail. C. Else if the range's current subtag matches the tag's current subtag, advance both pointers and continue. D. Else if the tag's current subtag is a "singleton" (a single letter or digit), fail. E. Else, advance the tag pointer only, and continue. 4. When the range's list is exhausted, the match succeeds.

$range	string
$lang	string
returns	bool

onInc($event)

I18n.php:127

#[MMO\core\attributes\Listen('MMO\\core\\events\\Inc')] function onInc(MMO\core\events\Inc $event): void

See: Inc event handler: registers a hook so the manifest also loads its translations for the current language once included.

$event	Inc
returns	void

setLanguage($lang)

I18n.php:139

Set language.

function setLanguage(string $lang): void

WARNING: PHP use _ instead of -

$lang	string	support _ and -
returns	void

splitLanguage($lang)

I18n.php:179

Match the full input against the RFC 5646 §2.1 'langtag' production:

function splitLanguage(string $lang): ?array

langtag = language ["-" script] ["-" region] *("-" variant) *("-" extension) ["-" privateuse] language = 2*3ALPHA ["-" extlang] / 4ALPHA / 5*8ALPHA extlang = 3ALPHA *2("-" 3ALPHA) script = 4ALPHA region = 2ALPHA / 3DIGIT variant = 5*8alphanum / (DIGIT 3alphanum) extension = singleton 1*("-" (2*8alphanum)) singleton = alphanum, excluding "x" / "X" privateuse = "x" 1*("-" (1*8alphanum)) Returns the regex match array, or null if the whole string doesn't conform.

$lang	string
returns	null \| array

translate($message, $context, $prefix, $lang)

I18n.php:110

Translate a message and its context

function translate( string $message, array $context = [], string $prefix = '', ?string $lang = null ): string

$message	string	the message (with/without placeholders)
$context = []	array	data to inject into the placeholders (also translated)
$prefix = ''	string	a prefix to add to every string to translate (ex: 'dates/')
$lang = null	null \| string
returns	string

translateDate($date, $lang)

I18n.php:295

Translate the textual parts of an already-formatted date (e.g. month/day names), via translations loaded under the /dates: prefix (getByPrefix/load).

function translateDate(string $date, ?string $lang = null): string

$date	string	an already-formatted date string, e.g. from `formatDate/`DateTime::format``.
$lang = null	null \| string
returns	string	$date with every matching `/dates:`-prefixed translation substituted in (`strtr`).

_($message, $context, $prefix, $lang)

staticI18n.php:54

Main entry point to translate a string

static function _( string $message, array $context = [], string $prefix = '', ?string $lang = null ): string

$message	string
$context = []	array
$prefix = ''	string
$lang = null	null \| string
returns	string

Inherited members (47)

Constants	Declared by	Description
`ALERT`	iLogLevel	Alert: Action must be taken immediately.
`ALL`	iLogLevel	Mask for all
`ALL_PLUS`	iLogLevel	debug everything
`BACKTRACE`	iLogLevel
`CRITICAL`	iLogLevel	Critical: Critical conditions.
`DEBUG`	iLogLevel	Debug: Detailed debug information.
`DEEP`	iLogLevel	debug everything with arguments
`EMERGENCY`	iLogLevel	Emergency: System is unusable.
`ERROR`	iLogLevel	Error: Runtime errors that do not require immediate action but should typically be logged and monitored.
`ERROR_PLUS`	iLogLevel	Mask for all error
`FATAL`	iLogLevel	Mask for all fatal error
`INFO`	iLogLevel	Info: Interesting events.
`INFO_PLUS`	iLogLevel	Mask for all errors/warning/notices/info
`MEMORY`	iLogLevel	include backtrace object
`NOTICE`	iLogLevel	Notice: Normal but significant events.
`NOTICE_PLUS`	iLogLevel	Mask for all errors/warning/notices/info
`TRACE`	iLogLevel	include backtrace as origins
`WARNING`	iLogLevel	Warning: Exceptional occurrences that are not errors.
`WARNING_PLUS`	iLogLevel	Mask for all errors and warnings

	Properties	Declared by	Description
	`verbosity`	aModule

Methods	Declared by	Description
`alert($message, $context)`	aModule	Action must be taken immediately.
`backtraces($message, $context)`	aModule	Force-log a message at INFO level together with a full stack trace/memory snapshot (`iLogLevel::BACKTRACE`), bypassing the verbosity mask entirely (any non-zero verbosity is enough to trigger it).
`Configure($config)`	aModule	Merge $config into this module's configuration in the shared `Configuration`.
`critical($message, $context)`	aModule	Critical conditions. No-op if CRITICAL is currently filtered out by the verbosity mask.
`debug($message, $context)`	aModule	Detailed debug information.
`debugName()`	aModule	Human-readable identifier used as the default `{origin}` in this instance's log messages.
`emergency($message, $context)`	aModule	System is unusable. No-op if EMERGENCY is currently filtered out by the verbosity mask.
`error($message, $context)`	aModule	Runtime errors that do not require immediate action but should typically be logged and monitored.
`getVerbosity()`	aModule
`info($message, $context)`	aModule	Interesting events. No-op if INFO is currently filtered out by the verbosity mask.
`Instantiate($config)`	aModule	(Re)create the shared instance immediately, configured with $config merged into the class's existing config.
`IsShared()`	aModule
`log($level, $message, $context)`	aModule	Logs with an arbitrary level.
`notice($message, $context)`	aModule	Normal but significant events.
`offsetExists($key)`	aModule	\ArrayAccess::offsetExists -- tells whether $key is a declared property at all, regardless of whether it is currently readable/writable through array access.
`offsetGet($key)`	aModule	\ArrayAccess::offsetGet -- reads a property directly, unless it has a `#[Serialize(serialize: 'methodName')]` attribute, in which case that zero-argument method is called instead (e.g.
`offsetSet($key, $value)`	aModule	\ArrayAccess::offsetSet -- sets a property directly, unless it has a `#[Serialize(unserialize: 'methodName')]` attribute, in which case that method is called with $value instead (e.g.
`offsetUnset($key)`	aModule	\ArrayAccess::offsetUnset -- equivalent to `$module[$key] = null`.
`serialize($path, $serializer)`	aModule	\MMO\core\interfaces\iSerializable::serialize -- exports every property (via
`setVerbosity($verb)`	aModule	Set the current verbosity mask, replacing whatever it was before.
`Shared()`	aModule	Get the shared instance, creating (and configuring) it on first call.
`testVerbosity($level)`	aModule	Test whether a given level (or set of levels) is currently enabled by this instance's verbosity mask.
`traitUnshare($serialize)`	aModule	Remove the shared instance, so the next `Shared()` call creates a fresh one.
`unserialize($data, $path, $instances)`	aModule	\MMO\core\interfaces\iSerializable::unserialize -- merges $data onto `DefaultConfig`, runs it through the (possibly overridden) constructor, then applies each resulting value to its property (via
`Unshare($serialize)`	aModule	Like `tSingleton::Unshare`, but also disconnects this module's instance from every event it was listening to (via `Event::DisconnectListeners`) before dropping it.
`warning($message, $context)`	aModule	Exceptional occurrences that are not errors.
`__construct($config)`	aModule	protected constructor, so it is not possible to do `new Module(...)` called by the serialization process just before being injected with data.