Translate

Reference for the Translate module: internationalisation and per-site terminology through one mechanism, named translation strings. Modules declare the user-facing strings they use with a default, or with a null default that forces the application to supply the text; values are stored per language and resolved at runtime in the active language.

This page is a pure reference. Modules declare their strings and the application supplies terminology and languages through TranslateConfig; a request resolves a Module.Name key to text with Translate::Text or its HTML-encoding Translate::h_Text (short-form globals t() and h_t()), which fall back to the source language when a translation is missing. Stored values live in the translate_string table accessed through TranslateStringDatabase.

Classes

Translate - runtime lookup that resolves a Module.Name key to text in the active language.
TranslateConfig - declare translation strings and languages, provide site terminology, and select the active language.
TranslateLanguageData - immutable data for a language the application supports.
TranslateStringData - immutable data for a single stored translation value in one language.
TranslateStringDatabase - database access for the translate_string table of stored translation values.

Translate

The runtime of the module: resolve a Module.Name key to text in the request's active language, filling any {{value}} insertion points. Resolution is database value, else app-provided default, else module default, so a missing translation falls back to the source language, never to the raw key. Loaded values are cached for the request.

Functions

ClearCache ExtractPlaceholders Text h_Text

ClearCache

Translate::ClearCache(): void

Clear the request cache of loaded translation values, for example after an admin edits a value in the same request.

Returns void

ExtractPlaceholders

Translate::ExtractPlaceholders(string $text): array

The unique double-brace placeholders present in a piece of text.

Name	Type	Description
`$text`	`string`	The text to scan for placeholders.

Returns array The placeholder names, unique.

Text

Translate::Text(string $key, array $params = []): string

Resolve a key to plain text in the active language and fill its insertion points. Short form: the global t(). The UI layer escapes the result. Throws when the key is not of the form Module.Name, when no value and no default exist, or when an expected insertion value is not provided.

Name	Type	Description
`$key`	`string`	A key of the form Module.Name.
`$params`	`array`	Values for the double-brace insertion points the text expects.

Returns string The resolved plain text.

h_Text

Translate::h_Text(string $key, array $params = []): string

Resolve a key to HTML-encoded text in the active language, ready to echo straight into markup. Short form: the global h_t(). Exactly Encode::Html applied to the plain result.

Name	Type	Description
`$key`	`string`	A key of the form Module.Name.
`$params`	`array`	Values for the double-brace insertion points the text expects.

Returns string The resolved, HTML-encoded text.

TranslateConfig

The configuration surface of the module: modules declare the strings they use, the application registers languages and provides source text (including the forced null-default terminology strings), and the active language for the request is selected here. A security check verifies the configuration is complete before a request is served.

Functions

AddLanguage AddString CurrentLanguage DefaultFor GetLanguages GetModules GetOptionalDefaultLanguage GetOptionalLanguage GetString GetStrings OptionalCurrentLanguage Provide SecurityCheck SetLanguage

AddLanguage

TranslateConfig::AddLanguage(string $code, string $subdomain, string $endonym, bool $isDefault = false): void

Name	Type	Description
`$code`	`string`	The language code.
`$subdomain`	`string`	The subdomain the language is served on; empty for the naked or www host.
`$endonym`	`string`	The language's own name, for a language switcher.
`$isDefault`	`bool`	Whether this is the default source language and fallback.

Returns void

AddString

TranslateConfig::AddString(string $module, string $name, ?string $default, array $params = [], string $group = ''): void

Declare a translation string. A null default forces the application to provide the text, which is how a site supplies its own terminology.

Name	Type	Description
`$module`	`string`	Owning module, the first segment of the key.
`$name`	`string`	String name, the rest of the key; may contain dot-separated enum segments.
`$default`	`?string`	Source-language default text; null means the application must provide it.
`$params`	`array`	Names of the double-brace insertion points the text expects.
`$group`	`string`	Optional grouping within the module, reserved for grouped loading.

Returns void

CurrentLanguage

TranslateConfig::CurrentLanguage(): string

The active language, or a failure when none was set. This is the guard that requires a language before any text is accessed.

Returns string The active language code.

DefaultFor

TranslateConfig::DefaultFor(string $module, string $name): ?string

The source-language default for a string: the app-provided text, else the module default, else null.

Name	Type	Description
`$module`	`string`	The owning module.
`$name`	`string`	The string name.

Returns ?string The default text, or null when there is none.

GetLanguages

TranslateConfig::GetLanguages(): array

The registered languages.

Returns array A list of TranslateLanguageData.

GetModules

TranslateConfig::GetModules(): array

Unique module names that have registered strings, sorted.

Returns array A list of module names.

GetOptionalDefaultLanguage

TranslateConfig::GetOptionalDefaultLanguage(): ?TranslateLanguageData

The registered default language, or null when none is marked default.

Returns ?TranslateLanguageData The default language, or null.

GetOptionalLanguage

TranslateConfig::GetOptionalLanguage(string $code): ?TranslateLanguageData

The registered language with a code, or null when none matches.

Name	Type	Description
`$code`	`string`	The language code to look up.

Returns ?TranslateLanguageData The language, or null.

GetString

TranslateConfig::GetString(string $module, string $name): ?stdClass

The registered schema entry for a string, or null when it is not registered.

Name	Type	Description
`$module`	`string`	The owning module.
`$name`	`string`	The string name.

Returns ?stdClass The schema entry, or null.

GetStrings

TranslateConfig::GetStrings(?string $module = null): array

Registered string schema entries, optionally filtered by module, sorted by name.

Name	Type	Description
`$module`	`?string`	A module name to filter by, or null for every entry.

Returns array The schema entries.

OptionalCurrentLanguage

TranslateConfig::OptionalCurrentLanguage(): ?string

The active language, or null when none has been set.

Returns ?string The active language code, or null.

Provide

TranslateConfig::Provide(string $module, array $values): void

Application supplies source text for a module's strings, typically the null-default ones it is forced to provide, though this may override any string's source text.

Name	Type	Description
`$module`	`string`	The module the values belong to.
`$values`	`array`	A map of string name to text.

Returns void

SecurityCheck

TranslateConfig::SecurityCheck(): void

Verify the configuration is complete and coherent: every string has a default or an app-provided value; if any languages are registered, exactly one is the default; and each source text's placeholders are all declared in that string's params. Throws when any check fails.

Returns void

SetLanguage

TranslateConfig::SetLanguage(string $code): void

Select the active language for the request from a registered code. Any selection strategy is fine as long as it happens before any text is accessed. Throws when the code is not registered.

Name	Type	Description
`$code`	`string`	A registered language code.

Returns void

TranslateLanguageData

Immutable data for a language the application supports, registered via TranslateConfig::AddLanguage. Fields and constructor only.

Properties

Property	Type	Description
`$language->code`	`string`	The language code (readonly).
`$language->subdomain`	`string`	The subdomain the language is served on; empty for the naked or www host (readonly).
`$language->endonym`	`string`	The language's own name (readonly).
`$language->isDefault`	`bool`	Whether this is the default source language and fallback (readonly).

__construct

new TranslateLanguageData(string $code = '', string $subdomain = '', string $endonym = '', bool $isDefault = false)

Create language data from a code, subdomain, endonym and default flag.

Name	Type	Description
`$code`	`string`	The language code.
`$subdomain`	`string`	The subdomain the language is served on.
`$endonym`	`string`	The language's own name.
`$isDefault`	`bool`	Whether this is the default language.

Returns TranslateLanguageData

TranslateStringData

Immutable data for a single stored translation value: the text for one string (module and name) in one language. The default source text lives in configuration, not here; these rows override the default per language. Fields and constructor only.

Properties

Property	Type	Description
`$data->id`	`int`	The row id (readonly).
`$data->module`	`string`	The owning module (readonly).
`$data->name`	`string`	The string name (readonly).
`$data->language`	`string`	The language code (readonly).
`$data->value`	`string`	The translated text (readonly).
`$data->addedTimestamp`	`int`	When the value was added or last set, as a Unix timestamp (readonly).

__construct

new TranslateStringData(int $id = 0, string $module = '', string $name = '', string $language = '', string $value = '', int $addedTimestamp = 0)

Create a stored translation value from its columns.

Name	Type	Description
`$id`	`int`	The row id.
`$module`	`string`	The owning module.
`$name`	`string`	The string name.
`$language`	`string`	The language code.
`$value`	`string`	The translated text.
`$addedTimestamp`	`int`	When the value was added or last set, as a Unix timestamp.

Returns TranslateStringData

TranslateStringDatabase

Database access for translation values in the translate_string table, owned entirely by this module and never joined to other modules' tables. A module, name and language triple is unique; saving upserts it.

Constants

Constant	Value	Description
`TranslateStringDatabase::TABLE`	`'translate_string'`	The table holding stored translation values.

Functions

DeleteById GetById GetForModuleLanguage GetOptional ListAll Upsert fromRow

DeleteById

TranslateStringDatabase::DeleteById(int $id): void

Delete a stored translation value by its id.

Name	Type	Description
`$id`	`int`	The row id.

Returns void

GetById

TranslateStringDatabase::GetById(int $id): TranslateStringData

Read one stored translation value by its id.

Name	Type	Description
`$id`	`int`	The row id.

Returns TranslateStringData The stored value.

GetForModuleLanguage

TranslateStringDatabase::GetForModuleLanguage(string $module, string $language): array

All stored values for a module in one language, as a name-to-value map. This is the unit the runtime caches, one query per module per language.

Name	Type	Description
`$module`	`string`	The owning module.
`$language`	`string`	The language code.

Returns array A map of string name to value.

GetOptional

TranslateStringDatabase::GetOptional(string $module, string $name, string $language): ?TranslateStringData

Read the stored value for a module, name and language, or null when there is none.

Name	Type	Description
`$module`	`string`	The owning module.
`$name`	`string`	The string name.
`$language`	`string`	The language code.

Returns ?TranslateStringData The stored value, or null.

ListAll

TranslateStringDatabase::ListAll(string $filterModule = '', string $filterLanguage = ''): array

All rows, optionally filtered by module and language, ordered for display. Empty filter strings mean no filter, so this also lists everything.

Name	Type	Description
`$filterModule`	`string`	A module to filter by, or empty for no module filter.
`$filterLanguage`	`string`	A language to filter by, or empty for no language filter.

Returns array A list of TranslateStringData.

Upsert

TranslateStringDatabase::Upsert(string $module, string $name, string $language, string $value): void

Insert a new value, or update the existing one for this module, name and language.

Name	Type	Description
`$module`	`string`	The owning module.
`$name`	`string`	The string name.
`$language`	`string`	The language code.
`$value`	`string`	The translated text to store.

Returns void

fromRow

TranslateStringDatabase::fromRow(stdClass $row): TranslateStringData

Map a database row object to a TranslateStringData.

Name	Type	Description
`$row`	`stdClass`	A row from the translate_string table.

Returns TranslateStringData The mapped value.