MediaWiki REL1_35
LanguageConverter Class Reference

Base class for multi-variant language conversion. More...

Inheritance diagram for LanguageConverter:
Collaboration diagram for LanguageConverter:

Public Member Functions

 __construct ( $langobj, $maincode, $variants=[], $variantfallbacks=[], $flags=[], $manualLevel=[])
 
 autoConvert ( $text, $toVariant=false)
 Dictionary-based conversion.
 
 autoConvertToAllVariants ( $text)
 Call translate() to convert text to all valid variants.
 
 convert ( $text)
 Convert text to different variants of a language.
 
 convertCategoryKey ( $key)
 Convert the sorting key for category links.
 
 convertHtml ( $text)
 Perform output conversion on a string, and encode for safe HTML output.
 
 convertNamespace ( $index, $variant=null)
 Get the namespace display name in the preferred variant.
 
 convertTitle (LinkTarget $linkTarget)
 Auto convert a LinkTarget object to a readable string in the preferred variant.
 
 convertTo ( $text, $variant)
 Same as convert() except a extra parameter to custom variant.
 
 findVariantLink (&$link, &$nt, $ignoreOtherCond=false)
 If a language supports multiple variants, it is possible that non-existing link in one variant actually exists in another variant.
 
 getConvRuleTitle ()
 Get the title produced by the conversion rule.
 
 getDefaultVariant ()
 Get default variant.
 
 getExtraHashOptions ()
 Returns language specific hash options.
 
 getPreferredVariant ()
 Get preferred language variant.
 
 getURLVariant ()
 Get the variant specified in the URL.
 
 getVariantFallbacks ( $variant)
 In case some variant is not defined in the markup, we need to have some fallback.
 
 getVariants ()
 Get all valid variants.
 
 getVarSeparatorPattern ()
 Get the cached separator pattern for ConverterRule::parseRules()
 
 guessVariant ( $text, $variant)
 Guess if a text is written in a variant.
 
 hasVariant ( $variant)
 Strict check if the language has the specific variant.
 
 hasVariants ()
 Check if this is a language with variants.
 
 markNoConversion ( $text, $noParse=false)
 Enclose a string with the "no conversion" tag.
 
 translate ( $text, $variant)
 Translate a string to a variant.
 
 updateConversionTable (LinkTarget $linkTarget)
 Refresh the cache of conversion tables when MediaWiki:Conversiontable* is updated.
 
 validateVariant ( $variant=null)
 Validate the variant and return an appropriate strict internal variant code if one exists.
 

Public Attributes

 $mDescCodeSep = ':'
 
 $mDescVarSep = ';'
 
 $mFlags
 
 $mMainLanguageCode
 
 $mManualLevel
 
 $mVariantNames
 
string[] $mVariants
 

Static Public Attributes

static array $languagesWithVariants
 languages supporting variants
 

Protected Member Functions

 applyManualConv (ConverterRule $convRule)
 Apply manual conversion rules.
 
 getHeaderVariant ()
 Determine the language variant from the Accept-Language header.
 
 getUserVariant (User $user)
 Determine if the user has a variant set.
 
 loadDefaultTables ()
 Load default conversion tables.
 
 loadTables ( $fromCache=true)
 Load conversion tables either from the cache or the disk.
 
 postLoadTables ()
 Hook for post processing after conversion tables are loaded.
 
 recursiveConvertRule ( $text, $variant, &$startPos, $depth=0)
 Recursively convert text on the inside.
 
 recursiveConvertTopLevel ( $text, $variant, $depth=0)
 Recursively convert text on the outside.
 

Protected Attributes

ReplacementArray[] bool[] $mTables
 

Private Member Functions

 parseCachedTable ( $code, $subpage='', $recursive=true)
 Parse the conversion table stored in the cache.
 
 reloadTables ()
 Reload the conversion tables.
 

Private Attributes

 $mConvRuleTitle = false
 
 $mHeaderVariant
 
Language $mLangObj
 
 $mMaxDepth = 10
 
 $mTablesLoaded = false
 
 $mUcfirst = false
 
 $mURLVariant
 
 $mUserVariant
 
 $mVariantFallbacks
 
 $mVarSeparatorPattern
 
const CACHE_VERSION_KEY = 'VERSION 7'
 

Detailed Description

Base class for multi-variant language conversion.

Definition at line 35 of file LanguageConverter.php.

Constructor & Destructor Documentation

◆ __construct()

LanguageConverter::__construct (   $langobj,
  $maincode,
  $variants = [],
  $variantfallbacks = [],
  $flags = [],
  $manualLevel = [] 
)
Parameters
Language$langobj
string$maincodeThe main language code of this language
string[]$variantsThe supported variants of this language
array$variantfallbacksThe fallback language of each variant
array$flagsDefining the custom strings that maps to the flags
array$manualLevelLimit for supported variants

Definition at line 100 of file LanguageConverter.php.

References $wgDisabledVariants, and deprecatePublicProperty().

Member Function Documentation

◆ applyManualConv()

LanguageConverter::applyManualConv ( ConverterRule  $convRule)
protected

Apply manual conversion rules.

Parameters
ConverterRule$convRule

Definition at line 587 of file LanguageConverter.php.

References ConverterRule\getConvTable(), ConverterRule\getRulesAction(), ConverterRule\getTitle(), and validateVariant().

Referenced by recursiveConvertRule().

◆ autoConvert()

LanguageConverter::autoConvert (   $text,
  $toVariant = false 
)

Dictionary-based conversion.

This function would not parse the conversion rules. If you want to parse rules, try to use convert() or convertTo().

Parameters
string$textThe text to be converted
bool | string$toVariantThe target language code
Returns
string The converted text

Implements ILanguageConverter.

Definition at line 396 of file LanguageConverter.php.

References StringUtils\explode(), getPreferredVariant(), guessVariant(), loadTables(), recursiveConvertTopLevel(), and translate().

Referenced by GanConverter\convertCategoryKey(), KkConverter\convertCategoryKey(), ZhConverter\convertCategoryKey(), recursiveConvertRule(), and recursiveConvertTopLevel().

◆ autoConvertToAllVariants()

LanguageConverter::autoConvertToAllVariants (   $text)

Call translate() to convert text to all valid variants.

Parameters
string$textThe text to be converted
Returns
array Variant => converted text

Implements ILanguageConverter.

Definition at line 571 of file LanguageConverter.php.

References loadTables(), and translate().

Referenced by findVariantLink().

◆ convert()

LanguageConverter::convert (   $text)

Convert text to different variants of a language.

The automatic conversion is done in autoConvert(). Here we parse the text marked with -{}-, which specifies special conversions of the text that can not be accomplished in autoConvert().

Syntax of the markup: -{code1:text1;code2:text2;...}- or -{flags|code1:text1;code2:text2;...}- or -{text}- in which case no conversion should take place for text

Warning
Glossary state is maintained between calls. Never feed this method input that hasn't properly been escaped as it may result in an XSS in subsequent calls, even if those subsequent calls properly escape things.
Parameters
string$textText to be converted, already html escaped.
Returns
string Converted text (html)

Implements ILanguageConverter.

Definition at line 707 of file LanguageConverter.php.

References convertTo(), and getPreferredVariant().

Referenced by convertHtml().

◆ convertCategoryKey()

LanguageConverter::convertCategoryKey (   $key)

Convert the sorting key for category links.

This should make different keys that are variants of each other map to the same key.

Parameters
string$key
Returns
string

Implements ILanguageConverter.

Reimplemented in GanConverter, KkConverter, and ZhConverter.

Definition at line 1188 of file LanguageConverter.php.

◆ convertHtml()

LanguageConverter::convertHtml (   $text)

Perform output conversion on a string, and encode for safe HTML output.

Since
1.35
Parameters
string$textText to be converted
Returns
string

Implements ILanguageConverter.

Definition at line 1286 of file LanguageConverter.php.

References convert().

◆ convertNamespace()

LanguageConverter::convertNamespace (   $index,
  $variant = null 
)

Get the namespace display name in the preferred variant.

Parameters
int$indexNamespace id
string | null$variantVariant code or null for preferred variant
Returns
string Namespace name for display

Implements ILanguageConverter.

Definition at line 645 of file LanguageConverter.php.

References $cache, Language\getFormattedNsText(), getPreferredVariant(), NS_MAIN, translate(), and wfMessage().

Referenced by convertTitle().

◆ convertTitle()

LanguageConverter::convertTitle ( LinkTarget  $linkTarget)

Auto convert a LinkTarget object to a readable string in the preferred variant.

Parameters
LinkTarget$linkTarget
Returns
string Converted title text

Implements ILanguageConverter.

Definition at line 625 of file LanguageConverter.php.

References convertNamespace(), MediaWiki\Linker\LinkTarget\getNamespace(), getPreferredVariant(), MediaWiki\Linker\LinkTarget\getText(), NS_MAIN, and translate().

◆ convertTo()

LanguageConverter::convertTo (   $text,
  $variant 
)

Same as convert() except a extra parameter to custom variant.

Parameters
string$textText to be converted, already html escaped
-taint$textexec_html
string$variantThe target variant code
Returns
string Converted text
-taint escaped

Implements ILanguageConverter.

Definition at line 721 of file LanguageConverter.php.

References $wgDisableLangConversion, and recursiveConvertTopLevel().

Referenced by convert().

◆ findVariantLink()

LanguageConverter::findVariantLink ( $link,
$nt,
  $ignoreOtherCond = false 
)

If a language supports multiple variants, it is possible that non-existing link in one variant actually exists in another variant.

This function tries to find it. See e.g. LanguageZh.php The input parameters may be modified upon return

Parameters
string&$linkThe name of the link
Title&$ntThe title object of the link
bool$ignoreOtherCondTo disable other conditions when we need to transclude a template or update a category's link

Implements ILanguageConverter.

Reimplemented in LanguageConverterSpecific.

Definition at line 873 of file LanguageConverter.php.

References $wgDisableLangConversion, $wgDisableTitleConversion, $wgRequest, autoConvertToAllVariants(), and NS_MAIN.

◆ getConvRuleTitle()

LanguageConverter::getConvRuleTitle ( )

Get the title produced by the conversion rule.

Returns
string The converted title text

Implements ILanguageConverter.

Definition at line 182 of file LanguageConverter.php.

◆ getDefaultVariant()

LanguageConverter::getDefaultVariant ( )

Get default variant.

This function would not be affected by user's settings

Returns
string The default variant code

Implements ILanguageConverter.

Definition at line 227 of file LanguageConverter.php.

References $wgDefaultLanguageVariant, getHeaderVariant(), getURLVariant(), and validateVariant().

◆ getExtraHashOptions()

LanguageConverter::getExtraHashOptions ( )

Returns language specific hash options.

Returns
string

Implements ILanguageConverter.

Definition at line 940 of file LanguageConverter.php.

References getPreferredVariant().

◆ getHeaderVariant()

LanguageConverter::getHeaderVariant ( )
protected

Determine the language variant from the Accept-Language header.

Returns
mixed Variant if one found, null otherwise

Definition at line 339 of file LanguageConverter.php.

References $wgRequest, getVariantFallbacks(), and validateVariant().

Referenced by getDefaultVariant(), and getPreferredVariant().

◆ getPreferredVariant()

LanguageConverter::getPreferredVariant ( )

Get preferred language variant.

Returns
string The preferred language code

Implements ILanguageConverter.

Definition at line 190 of file LanguageConverter.php.

References $wgDefaultLanguageVariant, getHeaderVariant(), getURLVariant(), getUserVariant(), and validateVariant().

Referenced by autoConvert(), convert(), convertNamespace(), convertTitle(), LanguageConverterSpecific\findVariantLink(), and getExtraHashOptions().

◆ getURLVariant()

LanguageConverter::getURLVariant ( )

Get the variant specified in the URL.

Returns
mixed Variant if one found, null otherwise

Implements ILanguageConverter.

Definition at line 283 of file LanguageConverter.php.

References $wgRequest, and validateVariant().

Referenced by getDefaultVariant(), and getPreferredVariant().

◆ getUserVariant()

LanguageConverter::getUserVariant ( User  $user)
protected

Determine if the user has a variant set.

Parameters
User$user
Returns
mixed Variant if one found, null otherwise

Definition at line 307 of file LanguageConverter.php.

References User\getOption(), User\isLoggedIn(), User\isSafeToLoad(), and validateVariant().

Referenced by getPreferredVariant().

◆ getVariantFallbacks()

LanguageConverter::getVariantFallbacks (   $variant)

In case some variant is not defined in the markup, we need to have some fallback.

For example, in zh, normally people will define zh-hans and zh-hant, but less so for zh-sg or zh-hk. when zh-sg is preferred but not defined, we will pick zh-hans in this case. Right now this is only used by zh.

Parameters
string$variantThe language code of the variant
Returns
string|array The code of the fallback language or the main code if there is no fallback

Implements ILanguageConverter.

Definition at line 174 of file LanguageConverter.php.

Referenced by getHeaderVariant().

◆ getVariants()

LanguageConverter::getVariants ( )

Get all valid variants.

Call this instead of using $this->mVariants directly.

Returns
string[] Contains all valid variants

Implements ILanguageConverter.

Definition at line 159 of file LanguageConverter.php.

Referenced by hasVariants().

◆ getVarSeparatorPattern()

LanguageConverter::getVarSeparatorPattern ( )

Get the cached separator pattern for ConverterRule::parseRules()

Returns
string

Definition at line 1214 of file LanguageConverter.php.

◆ guessVariant()

LanguageConverter::guessVariant (   $text,
  $variant 
)

Guess if a text is written in a variant.

This should be implemented in subclasses.

Parameters
string$textThe text to be checked
string$variantLanguage code of the variant to be checked for
Returns
bool True if $text appears to be written in $variant, false if not
Author
Nikola Smolenski smole.nosp@m.nsk@.nosp@m.eunet.nosp@m..rs
Since
1.19

Implements ILanguageConverter.

Reimplemented in SrConverter.

Definition at line 956 of file LanguageConverter.php.

Referenced by autoConvert(), and recursiveConvertTopLevel().

◆ hasVariant()

LanguageConverter::hasVariant (   $variant)

Strict check if the language has the specific variant.

Compare to LanguageConverter::validateVariant() which does a more lenient check and attempts to coerce the given code to a valid one.

Since
1.35
Parameters
string$variant
Returns
bool

Implements ILanguageConverter.

Definition at line 1274 of file LanguageConverter.php.

References validateVariant().

◆ hasVariants()

LanguageConverter::hasVariants ( )

Check if this is a language with variants.

Since
1.35
Returns
bool

Implements ILanguageConverter.

Definition at line 1260 of file LanguageConverter.php.

References getVariants().

◆ loadDefaultTables()

LanguageConverter::loadDefaultTables ( )
protected

Load default conversion tables.

This method must be implemented in derived class.

Exceptions
MWException

Reimplemented in EnConverter, GanConverter, IuConverter, KkConverter, KuConverter, ShiConverter, SrConverter, TgConverter, UzConverter, and ZhConverter.

Definition at line 966 of file LanguageConverter.php.

Referenced by loadTables().

◆ loadTables()

LanguageConverter::loadTables (   $fromCache = true)
protected

Load conversion tables either from the cache or the disk.

Access:\n private
Parameters
bool$fromCacheLoad from memcached? Defaults to true.

Definition at line 976 of file LanguageConverter.php.

References $cache, $wgLanguageConverterCacheType, loadDefaultTables(), parseCachedTable(), and postLoadTables().

Referenced by autoConvert(), autoConvertToAllVariants(), reloadTables(), IuConverter\translate(), KuConverter\translate(), ShiConverter\translate(), SrConverter\translate(), and translate().

◆ markNoConversion()

LanguageConverter::markNoConversion (   $text,
  $noParse = false 
)

Enclose a string with the "no conversion" tag.

This is used by various functions in the Parser.

Parameters
string$textText to be tagged for no conversion
bool$noParseUnused
Returns
string The tagged text

Implements ILanguageConverter.

Definition at line 1170 of file LanguageConverter.php.

◆ parseCachedTable()

LanguageConverter::parseCachedTable (   $code,
  $subpage = '',
  $recursive = true 
)
private

Parse the conversion table stored in the cache.

The tables should be in blocks of the following form: -{ word => word ; word => word ; ... }-

To make the tables more manageable, subpages are allowed and will be parsed recursively if $recursive == true.

Parameters
string$codeLanguage code
string$subpageSubpage name
bool$recursiveParse subpages recursively? Defaults to true.
Returns
array

Definition at line 1052 of file LanguageConverter.php.

References $s, $t, $title, CONTENT_MODEL_WIKITEXT, StringUtils\explode(), NS_MEDIAWIKI, and parseCachedTable().

Referenced by loadTables(), and parseCachedTable().

◆ postLoadTables()

LanguageConverter::postLoadTables ( )
protected

Hook for post processing after conversion tables are loaded.

Reimplemented in KkConverter, and ZhConverter.

Definition at line 1013 of file LanguageConverter.php.

Referenced by loadTables().

◆ recursiveConvertRule()

LanguageConverter::recursiveConvertRule (   $text,
  $variant,
$startPos,
  $depth = 0 
)
protected

Recursively convert text on the inside.

Parameters
string$textText to be converted
string$variantThe target variant code
int&$startPos
int$depthDepth of recursion
Exceptions
MWException
Returns
string Converted text

Definition at line 795 of file LanguageConverter.php.

References applyManualConv(), autoConvert(), recursiveConvertRule(), and wfMessage().

Referenced by recursiveConvertRule(), and recursiveConvertTopLevel().

◆ recursiveConvertTopLevel()

LanguageConverter::recursiveConvertTopLevel (   $text,
  $variant,
  $depth = 0 
)
protected

Recursively convert text on the outside.

Allow to use nested markups to custom rules.

Parameters
string$textText to be converted
string$variantThe target variant code
int$depthDepth of recursion
Returns
string Converted text

Definition at line 740 of file LanguageConverter.php.

References autoConvert(), guessVariant(), and recursiveConvertRule().

Referenced by autoConvert(), and convertTo().

◆ reloadTables()

LanguageConverter::reloadTables ( )
private

Reload the conversion tables.

Also used by test suites which need to reset the converter state.

Access:\n private

Definition at line 1023 of file LanguageConverter.php.

References loadTables().

Referenced by updateConversionTable().

◆ translate()

LanguageConverter::translate (   $text,
  $variant 
)

Translate a string to a variant.

Doesn't parse rules or do any of that other stuff, for that use convert() or convertTo().

Parameters
string$textText to convert
string$variantVariant language code
Returns
string Translated text

Implements ILanguageConverter.

Reimplemented in EnConverter, IuConverter, KkConverter, KuConverter, ShiConverter, SrConverter, and UzConverter.

Definition at line 555 of file LanguageConverter.php.

References loadTables().

Referenced by autoConvert(), autoConvertToAllVariants(), convertNamespace(), and convertTitle().

◆ updateConversionTable()

LanguageConverter::updateConversionTable ( LinkTarget  $linkTarget)

Refresh the cache of conversion tables when MediaWiki:Conversiontable* is updated.

Parameters
LinkTarget$linkTargetThe LinkTarget of the page being updated

Implements ILanguageConverter.

Definition at line 1198 of file LanguageConverter.php.

References $t, MediaWiki\Linker\LinkTarget\getDBkey(), MediaWiki\Linker\LinkTarget\getNamespace(), NS_MEDIAWIKI, reloadTables(), and validateVariant().

◆ validateVariant()

LanguageConverter::validateVariant (   $variant = null)

Validate the variant and return an appropriate strict internal variant code if one exists.

Compare to Language::hasVariant() which does a strict test.

Parameters
string | null$variantThe variant to validate
Returns
mixed Returns an equivalent valid variant code if possible, null otherwise

Implements ILanguageConverter.

Definition at line 255 of file LanguageConverter.php.

Referenced by applyManualConv(), getDefaultVariant(), getHeaderVariant(), getPreferredVariant(), getURLVariant(), getUserVariant(), hasVariant(), and updateConversionTable().

Member Data Documentation

◆ $languagesWithVariants

array LanguageConverter::$languagesWithVariants
static
Initial value:
= [
'en',
'crh',
'gan',
'iu',
'kk',
'ku',
'shi',
'sr',
'tg',
'uz',
'zh',
]

languages supporting variants

Since
1.20

Definition at line 43 of file LanguageConverter.php.

◆ $mConvRuleTitle

LanguageConverter::$mConvRuleTitle = false
private

Definition at line 83 of file LanguageConverter.php.

◆ $mDescCodeSep

LanguageConverter::$mDescCodeSep = ':'

Definition at line 80 of file LanguageConverter.php.

◆ $mDescVarSep

LanguageConverter::$mDescVarSep = ';'

Definition at line 81 of file LanguageConverter.php.

◆ $mFlags

LanguageConverter::$mFlags

Definition at line 79 of file LanguageConverter.php.

◆ $mHeaderVariant

LanguageConverter::$mHeaderVariant
private

Definition at line 86 of file LanguageConverter.php.

◆ $mLangObj

Language LanguageConverter::$mLangObj
private

Definition at line 78 of file LanguageConverter.php.

◆ $mMainLanguageCode

LanguageConverter::$mMainLanguageCode

Definition at line 57 of file LanguageConverter.php.

◆ $mManualLevel

LanguageConverter::$mManualLevel

Definition at line 73 of file LanguageConverter.php.

◆ $mMaxDepth

LanguageConverter::$mMaxDepth = 10
private

Definition at line 87 of file LanguageConverter.php.

◆ $mTables

ReplacementArray [] bool [] LanguageConverter::$mTables
protected

Definition at line 70 of file LanguageConverter.php.

◆ $mTablesLoaded

LanguageConverter::$mTablesLoaded = false
private

Definition at line 65 of file LanguageConverter.php.

◆ $mUcfirst

LanguageConverter::$mUcfirst = false
private

Definition at line 82 of file LanguageConverter.php.

◆ $mURLVariant

LanguageConverter::$mURLVariant
private

Definition at line 84 of file LanguageConverter.php.

◆ $mUserVariant

LanguageConverter::$mUserVariant
private

Definition at line 85 of file LanguageConverter.php.

◆ $mVariantFallbacks

LanguageConverter::$mVariantFallbacks
private

Definition at line 63 of file LanguageConverter.php.

◆ $mVariantNames

LanguageConverter::$mVariantNames

Definition at line 64 of file LanguageConverter.php.

◆ $mVariants

string [] LanguageConverter::$mVariants

Definition at line 62 of file LanguageConverter.php.

◆ $mVarSeparatorPattern

LanguageConverter::$mVarSeparatorPattern
private

Definition at line 88 of file LanguageConverter.php.

◆ CACHE_VERSION_KEY

const LanguageConverter::CACHE_VERSION_KEY = 'VERSION 7'
private

Definition at line 90 of file LanguageConverter.php.


The documentation for this class was generated from the following file: