Documentation

Lang
in package

SMF

uses BackwardCompatibility

Handles the localizable strings shown in SMF's user interface.

Constants

LANG_TO_LOCALE = [ 'albanian' => 'sq_AL', // 001 is the region code the whole world, so this means modern standard Arabic. 'arabic' => 'ar_001', 'bulgarian' => 'bg_BG', 'cambodian' => 'km_KH', 'catalan' => 'ca_ES', 'chinese-simplified' => 'zh_Hans', 'chinese-traditional' => 'zh_Hant', 'croatian' => 'hr_HR', 'czech' => 'cs_CZ', // Since 'informal' is not a locale, we just map this to the 'root' locale. 'czech_informal' => 'cs', 'danish' => 'da_DK', 'dutch' => 'nl_NL', 'english' => 'en_US', 'english_british' => 'en_GB', // english_pirate isn't a real language, so we use the _x_ to mark it as a 'private language'. 'english_pirate' => 'en_x_pirate', 'esperanto' => 'eo', 'finnish' => 'fi_FI', 'french' => 'fr_FR', 'galician' => 'gl_ES', 'german' => 'de_DE', // Since 'informal' is not a locale, we just map this to the 'root' locale. 'german_informal' => 'de', 'greek' => 'el_GR', 'hebrew' => 'he_IL', 'hungarian' => 'hu_HU', 'indonesian' => 'id_ID', 'italian' => 'it_IT', 'japanese' => 'ja_JP', 'lithuanian' => 'lt_LT', 'macedonian' => 'mk_MK', 'malay' => 'ms_MY', 'norwegian' => 'nb_NO', 'persian' => 'fa_IR', 'polish' => 'pl_PL', 'portuguese_brazilian' => 'pt_BR', 'portuguese_pt' => 'pt_PT', 'romanian' => 'ro_RO', 'russian' => 'ru_RU', // Cyrl indicates Cyrillic script. 'serbian_cyrillic' => 'sr_Cyrl', // Latn indicates Latin script. 'serbian_latin' => 'sr_Latn', 'slovak' => 'sk_SK', 'slovenian' => 'sl_SI', 'spanish_es' => 'es_ES', // 419 is the region code for Latin America. 'spanish_latin' => 'es_419', 'swedish' => 'sv_SE', 'thai' => 'th_TH', 'turkish' => 'tr_TR', 'ukrainian' => 'uk_UA', 'urdu' => 'ur_PK', 'vietnamese' => 'vi_VN', ]: Maps SMF 2.x language names to locales for SMF 3.0+.

Properties

$decimal_separator : string
$default : string
$digit_group_separator : string
$dirs : array<string|int, mixed>
$editortxt : array<string|int, mixed>
$forum_copyright : string
$helptxt : array<string|int, mixed>
$txt : array<string|int, mixed>
$txtBirthdayEmails : array<string|int, mixed>
$tztxt : array<string|int, mixed>
$already_loaded : array<string|int, mixed>
$backcompat : array<string|int, mixed>
$localized_copyright : array<string|int, mixed>

Methods

addDirs() : void: Populates Lang::$dirs with paths to language directories.
censorText() : string: Replace all vulgar words with respective proper words. (substring or whole words..) What this function does: - it censors the passed string.
exportStatic() : void: Provides a way to export a class's public static properties and methods to global namespace.
formatText() : string: Formats a MessageFormat or sprintf string using the supplied arguments.
get() : array<string|int, mixed>: Attempt to reload our known languages.
getLocaleFromLanguageName() : string|null: Given an SMF 2.x language name, returns the locale code for SMF 3.0+.
getTxt() : string: High level method that retrieves language strings, inserts any arguments into them, and then returns the resulting finalized string.
load() : string: Load a language file.
loadOld() : bool: A backward compatibility method for loading language files with old names.
numberFormat() : string: Locale-aware replacement for number_format().
sentenceList() : string: Concatenates an array of strings into a grammatically correct sentence list.
tokenTxtReplace() : string: Replaces tokens in a string with values from Lang::$txt.

LANG_TO_LOCALE

Maps SMF 2.x language names to locales for SMF 3.0+.


    public
        mixed
    LANG_TO_LOCALE
    = [
    'albanian' => 'sq_AL',
    // 001 is the region code the whole world, so this means modern standard Arabic.
    'arabic' => 'ar_001',
    'bulgarian' => 'bg_BG',
    'cambodian' => 'km_KH',
    'catalan' => 'ca_ES',
    'chinese-simplified' => 'zh_Hans',
    'chinese-traditional' => 'zh_Hant',
    'croatian' => 'hr_HR',
    'czech' => 'cs_CZ',
    // Since 'informal' is not a locale, we just map this to the 'root' locale.
    'czech_informal' => 'cs',
    'danish' => 'da_DK',
    'dutch' => 'nl_NL',
    'english' => 'en_US',
    'english_british' => 'en_GB',
    // english_pirate isn't a real language, so we use the _x_ to mark it as a 'private language'.
    'english_pirate' => 'en_x_pirate',
    'esperanto' => 'eo',
    'finnish' => 'fi_FI',
    'french' => 'fr_FR',
    'galician' => 'gl_ES',
    'german' => 'de_DE',
    // Since 'informal' is not a locale, we just map this to the 'root' locale.
    'german_informal' => 'de',
    'greek' => 'el_GR',
    'hebrew' => 'he_IL',
    'hungarian' => 'hu_HU',
    'indonesian' => 'id_ID',
    'italian' => 'it_IT',
    'japanese' => 'ja_JP',
    'lithuanian' => 'lt_LT',
    'macedonian' => 'mk_MK',
    'malay' => 'ms_MY',
    'norwegian' => 'nb_NO',
    'persian' => 'fa_IR',
    'polish' => 'pl_PL',
    'portuguese_brazilian' => 'pt_BR',
    'portuguese_pt' => 'pt_PT',
    'romanian' => 'ro_RO',
    'russian' => 'ru_RU',
    // Cyrl indicates Cyrillic script.
    'serbian_cyrillic' => 'sr_Cyrl',
    // Latn indicates Latin script.
    'serbian_latin' => 'sr_Latn',
    'slovak' => 'sk_SK',
    'slovenian' => 'sl_SI',
    'spanish_es' => 'es_ES',
    // 419 is the region code for Latin America.
    'spanish_latin' => 'es_419',
    'swedish' => 'sv_SE',
    'thai' => 'th_TH',
    'turkish' => 'tr_TR',
    'ukrainian' => 'uk_UA',
    'urdu' => 'ur_PK',
    'vietnamese' => 'vi_VN',
]

This is used to support upgrading from SMF 2.1 and below.

$decimal_separator


    public
    static    string
    $decimal_separator

Decimal separator to use in Lang::numberFormat.

$default


    public
    static    string
    $default

Local copy of SMF\Config::$language

$digit_group_separator


    public
    static    string
    $digit_group_separator

Thousands separator to use in Lang::numberFormat.

$dirs


    public
    static    array<string|int, mixed>
    $dirs
     = []

Language file directories.

$editortxt


    public
    static    array<string|int, mixed>
    $editortxt
     = []

Array of localized strings for the editor UI.

$forum_copyright


    public
    static    string
    $forum_copyright
     = '<a href="{scripturl}?action=credits" title="License" target="_blank" rel="noopener">{version} &copy; {year}</a>, <a href="https://www.simplemachines.org" title="Simple Machines" target="_blank" rel="noopener">Simple Machines</a>'

MessageFormat string to show the SMF copyright. The default value will be overwritten when a language is loaded.

$helptxt


    public
    static    array<string|int, mixed>
    $helptxt
     = []

Array of localized strings for the admin help popup.

$txt


    public
    static    array<string|int, mixed>
    $txt
     = []

Array of localized strings for the UI.

$txtBirthdayEmails


    public
    static    array<string|int, mixed>
    $txtBirthdayEmails
     = []

Array of localized strings for birthday emails.

$tztxt


    public
    static    array<string|int, mixed>
    $tztxt
     = []

Array of localized strings for time zone "meta-zones".

$already_loaded


    private
    static    array<string|int, mixed>
    $already_loaded
     = []

Tracks which language files we have loaded.

$backcompat


    private
    static    array<string|int, mixed>
    $backcompat
     = ['prop_names' => ['txt' => 'txt', 'tztxt' => 'tztxt', 'editortxt' => 'editortxt', 'helptxt' => 'helptxt', 'txtBirthdayEmails' => 'txtBirthdayEmails', 'forum_copyright' => 'forum_copyright']]

BackwardCompatibility settings for this class.

$localized_copyright


    private
    static    array<string|int, mixed>
    $localized_copyright
     = []

Tracks the value of $forum_copyright for different languages.

addDirs()

Populates Lang::$dirs with paths to language directories.


    public
            static        addDirs([array<string|int, mixed>|string $custom_dirs = [] ]) : void

If $custom_dirs is empty, Lang::$dirs will be populated with the standard language directories in the current theme, the current theme's base theme (if applicable), and the default theme.

If $custom_dirs is set to one or more directory paths, those paths will be prepended to Lang::$dirs.

Parameters

$custom_dirs : array<string|int, mixed>|string = []: Optional custom directories to include.

censorText()

Replace all vulgar words with respective proper words. (substring or whole words..) What this function does: - it censors the passed string.


    public
            static        censorText(string &$text[, bool $force = false ]) : string

if the theme setting allow_no_censored is on, and the theme option show_no_censored is enabled, does not censor, unless force is also set.
it caches the list of censored words to reduce parsing.

Parameters

$text : string: The text to censor
$force : bool = false: Whether to censor the text regardless of settings

Return values

string —

The censored text

exportStatic()

Provides a way to export a class's public static properties and methods to global namespace.


    public
            static        exportStatic() : void

To do so:

Use this trait in the class.
At the END of the class's file, call its exportStatic() method.

Although it might not seem that way at first glance, this approach conforms to section 2.3 of PSR 1, since executing this method is simply a dynamic means of declaring functions when the file is included; it has no other side effects.

Regarding the $backcompat items:

A class's static properties are not exported to global variables unless explicitly included in $backcompat['prop_names'].

$backcompat['prop_names'] is a simple array where the keys are the names of one or more of a class's static properties, and the values are the names of global variables. In each case, the global variable will be set to a reference to the static property. Static properties that are not named in this array will not be exported.

Adding non-static properties to the $backcompat arrays will produce runtime errors. It is the responsibility of the developer to make sure not to do this.

formatText()

Formats a MessageFormat or sprintf string using the supplied arguments.


    public
            static        formatText(string $message[, array<string|int, mixed> $args = [] ]) : string

Parameters

$message : string: The MessageFormat or sprintf string.
$args : array<string|int, mixed> = []: Arguments to use in the string.

Return values

string —

The formatted string.

get()

Attempt to reload our known languages.


    public
            static        get([bool $use_cache = true ]) : array<string|int, mixed>

It will try to choose only utf8 or non-utf8 languages.

Parameters

$use_cache : bool = true: Whether or not to use the cache

Return values

array<string|int, mixed> —

An array of information about available languages

getLocaleFromLanguageName()

Given an SMF 2.x language name, returns the locale code for SMF 3.0+.


    public
            static        getLocaleFromLanguageName(string $lang) : string|null

This is used to support upgrading from SMF 2.1 and below. This is also used to support compatibility for customizations.

If $lang is already a supported locale, it will simply be returned.

Languages can map to:

null: No translation. Language is removed and no upgrade is possible.
A locale: The locale code for the language.

Parameters

$lang : string: Language name

Return values

string|null —

Locale is returned if found, null otherwise.

getTxt()

High level method that retrieves language strings, inserts any arguments into them, and then returns the resulting finalized string.


    public
            static        getTxt(string|array<string|int, mixed> $txt_key[, array<string|int, mixed> $args = [] ][, string $var = 'txt' ]) : string

If no arguments are supplied in $args, this method simply returns the requested string.

If arguments are supplied in $args, this method will insert them into the requested string. The method can handle argument substitution for both MessageFormat and sprintf format strings.

Parameters

$txt_key : string|array<string|int, mixed>: The key of the Lang::$txt array that contains the desired string. If this is an array, each item of the array will be used as a sub-key to drill down into deeper levels of the overall array.
$args : array<string|int, mixed> = []: Arguments to substitute into the Lang::$txt string.
$var : string = 'txt': Name of the array to search in. Default: 'txt'. Other possible values are 'helptxt', 'editortxt', and 'tztxt'.

Return values

string —

The string to display to the user.

load()

Load a language file.


    public
            static        load(string $template_name[, string $lang = '' ][, bool $fatal = true ][, bool $force_reload = false ]) : string

Tries the current and default themes as well as the user and global languages.

Parameters

$template_name : string: The name of a template file.
$lang : string = '': A specific language to load this file from.
$fatal : bool = true: Whether to die with an error if it can't be loaded.
$force_reload : bool = false: Whether to load the file again if it's already loaded.

Return values

string —

The language actually loaded.

loadOld()

A backward compatibility method for loading language files with old names.


    public
            static        loadOld(array<string|int, mixed> $attempts) : bool

Only used to support compatibility with old name formats.

This is used to support backward compatibility with mods from SMF 2.1. Do not rely on this method to exist in future versions!

Parameters

$attempts : array<string|int, mixed>: The attempts to be made; see self::load().

Return values

bool —

Whether we loaded anything or not.

numberFormat()

Locale-aware replacement for number_format().


    public
            static        numberFormat(int|float|string $number[, int|null $decimals = null ]) : string

Always uses the decimal separator and digit group separator for the current locale to format the number.

Parameters

$number : int|float|string: A number.
$decimals : int|null = null: If set, will use the specified number of decimal places. Otherwise, it's automatically determined.

Return values

string —

A formatted number

sentenceList()

Concatenates an array of strings into a grammatically correct sentence list.


    public
            static        sentenceList(array<string|int, mixed> $list[, string $type = 'and' ]) : string

Uses formats defined in the language files to build the list according to the rules for the currently loaded language.

Parameters

$list : array<string|int, mixed>: An array of strings to concatenate.
$type : string = 'and': Either 'and', 'or', or 'xor'. Default: 'and'.

Return values

string —

The localized sentence list.

tokenTxtReplace()

Replaces tokens in a string with values from Lang::$txt.


    public
            static        tokenTxtReplace([string $string = '' ]) : string

Tokens take the form of '{key}', where 'key' is the key of some element in the Lang::$txt array.

Parameters

$string : string = '': The string in which to make replacements.

Return values

string —

The updated string.

Lang in package SMF uses BackwardCompatibility

Table of Contents

Constants

Properties

Methods

Constants

LANG_TO_LOCALE

Properties

$decimal_separator

$default

$digit_group_separator

$dirs

$editortxt

$forum_copyright

$helptxt

$txt

$txtBirthdayEmails

$tztxt

$already_loaded

$backcompat

$localized_copyright

Methods

addDirs()

Parameters

censorText()

Parameters

Return values

exportStatic()

formatText()

Parameters

Return values

get()

Parameters

Return values

getLocaleFromLanguageName()

Parameters

Return values

getTxt()

Parameters

Return values

load()

Parameters

Return values

loadOld()

Parameters

Return values

numberFormat()

Parameters

Return values

sentenceList()

Parameters

Return values

tokenTxtReplace()

Parameters

Return values

Lang
in package

SMF

uses BackwardCompatibility