281 lines
8.4 KiB
PHP
281 lines
8.4 KiB
PHP
<?php
|
|
/**
|
|
* This program is free software; you can redistribute it and/or modify
|
|
* it under the terms of the GNU General Public License as published by
|
|
* the Free Software Foundation; either version 2 of the License, or
|
|
* (at your option) any later version.
|
|
*
|
|
* This program is distributed in the hope that it will be useful,
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
* GNU General Public License for more details.
|
|
*
|
|
* You should have received a copy of the GNU General Public License along
|
|
* with this program; if not, write to the Free Software Foundation, Inc.,
|
|
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
|
|
* http://www.gnu.org/copyleft/gpl.html
|
|
*
|
|
* @file
|
|
*/
|
|
|
|
namespace MediaWiki\Language;
|
|
|
|
use MediaWiki\Linker\LinkTarget;
|
|
use MediaWiki\Page\PageReference;
|
|
use MediaWiki\Title\Title;
|
|
|
|
/**
|
|
* The shared interface for all language converters.
|
|
*
|
|
* @ingroup Language
|
|
* @internal
|
|
*/
|
|
interface ILanguageConverter {
|
|
|
|
/**
|
|
* Get all valid variants.
|
|
*
|
|
* @return string[] Contains all valid variants
|
|
*/
|
|
public function getVariants();
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* @param string $variant The language code of the variant
|
|
* @return string|array The code of the fallback language or the
|
|
* main code if there is no fallback
|
|
*/
|
|
public function getVariantFallbacks( $variant );
|
|
|
|
/**
|
|
* Get the title produced by the conversion rule.
|
|
*
|
|
* @return string|false The converted title text
|
|
*/
|
|
public function getConvRuleTitle();
|
|
|
|
/**
|
|
* Get preferred language variant.
|
|
*
|
|
* @return string The preferred language code
|
|
*/
|
|
public function getPreferredVariant();
|
|
|
|
/**
|
|
* This function would not be affected by user's settings
|
|
*
|
|
* @return string The default variant code
|
|
*/
|
|
public function getDefaultVariant();
|
|
|
|
/**
|
|
* Validate the variant and return an appropriate strict internal
|
|
* variant code if one exists. Compare to Language::hasVariant()
|
|
* which does a strict test.
|
|
*
|
|
* @param string|null $variant The variant to validate
|
|
* @return string|null Returns an equivalent valid variant code if possible,
|
|
* null otherwise
|
|
*/
|
|
public function validateVariant( $variant = null );
|
|
|
|
/**
|
|
* Get the variant specified in the URL
|
|
*
|
|
* @return string|null Variant if one found, null otherwise
|
|
*/
|
|
public function getURLVariant();
|
|
|
|
/**
|
|
* Dictionary-based conversion.
|
|
* This function would not parse the conversion rules.
|
|
* If you want to parse rules, try to use convert() or
|
|
* convertTo().
|
|
*
|
|
* @param string $text The text to be converted
|
|
* @param string|false $toVariant The target language code
|
|
* @return string The converted text
|
|
*/
|
|
public function autoConvert( $text, $toVariant = false );
|
|
|
|
/**
|
|
* Translate a string to a variant.
|
|
* Doesn't parse rules or do any of that other stuff, for that use
|
|
* convert() or convertTo().
|
|
*
|
|
* @param string $text Text to convert
|
|
* @param string $variant Variant language code
|
|
* @return string Translated text
|
|
*/
|
|
public function translate( $text, $variant );
|
|
|
|
/**
|
|
* Call translate() to convert text to all valid variants.
|
|
*
|
|
* @param string $text The text to be converted
|
|
* @return array Variant => converted text
|
|
*/
|
|
public function autoConvertToAllVariants( $text );
|
|
|
|
/**
|
|
* Automatically converts a LinkTarget or PageReference to a readable string in the
|
|
* preferred variant, separating the namespace and the main part of the title.
|
|
*
|
|
* @since 1.39
|
|
* @param LinkTarget|PageReference $title
|
|
* @return string[] Three elements: converted namespace text, converted namespace separator,
|
|
* and the converted main part of the title
|
|
*/
|
|
public function convertSplitTitle( $title );
|
|
|
|
/**
|
|
* Automatically convert a LinkTarget or PageReference to a readable string in the
|
|
* preferred variant.
|
|
*
|
|
* @param LinkTarget|PageReference $title
|
|
* @return string Converted title text
|
|
*/
|
|
public function convertTitle( $title );
|
|
|
|
/**
|
|
* Get the namespace display name in the preferred variant.
|
|
*
|
|
* @param int $index Namespace id
|
|
* @param string|null $variant Variant code or null for preferred variant
|
|
* @return string Namespace name for display
|
|
*/
|
|
public function convertNamespace( $index, $variant = null );
|
|
|
|
/**
|
|
* 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 cannot 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.
|
|
* @param string $text Text to be converted; already html escaped.
|
|
* @return string Converted text (html)
|
|
*/
|
|
public function convert( $text );
|
|
|
|
/**
|
|
* Same as convert() except a extra parameter to custom variant.
|
|
*
|
|
* @param string $text Text to be converted; already html escaped
|
|
* @param-taint $text exec_html
|
|
* @param string $variant The target variant code
|
|
* @param bool $clearState Whether to clear the converter title before
|
|
* conversion (defaults to true)
|
|
* @return string Converted text
|
|
* @return-taint escaped
|
|
*/
|
|
public function convertTo( $text, $variant, bool $clearState = true );
|
|
|
|
/**
|
|
* 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
|
|
*
|
|
* @param string &$link The name of the link
|
|
* @param Title &$nt The title object of the link
|
|
* @param bool $ignoreOtherCond To disable other conditions when
|
|
* we need to transclude a template or update a category's link
|
|
*/
|
|
public function findVariantLink( &$link, &$nt, $ignoreOtherCond = false );
|
|
|
|
/**
|
|
* Returns language specific hash options.
|
|
*
|
|
* @return string
|
|
*/
|
|
public function getExtraHashOptions();
|
|
|
|
/**
|
|
* Guess if a text is written in a variant. This should be implemented in subclasses.
|
|
*
|
|
* @param string $text The text to be checked
|
|
* @param string $variant Language code of the variant to be checked for
|
|
* @return bool True if $text appears to be written in $variant, false if not
|
|
*
|
|
* @author Nikola Smolenski <smolensk@eunet.rs>
|
|
* @since 1.19
|
|
*/
|
|
public function guessVariant( $text, $variant );
|
|
|
|
/**
|
|
* Enclose a string with the "no conversion" tag. This is used by
|
|
* various functions in the Parser.
|
|
*
|
|
* @param string $text Text to be tagged for no conversion
|
|
* @param bool $noParse Unused
|
|
* @return string The tagged text
|
|
*/
|
|
public function markNoConversion( $text, $noParse = false );
|
|
|
|
/**
|
|
* Convert the sorting key for category links. This should make different
|
|
* keys that are variants of each other map to the same key.
|
|
*
|
|
* @param string $key
|
|
*
|
|
* @return string
|
|
*/
|
|
public function convertCategoryKey( $key );
|
|
|
|
/**
|
|
* Refresh the cache of conversion tables when
|
|
* MediaWiki:Conversiontable* is updated.
|
|
*
|
|
* @param LinkTarget $linkTarget The LinkTarget of the page being updated
|
|
*/
|
|
public function updateConversionTable( LinkTarget $linkTarget );
|
|
|
|
/**
|
|
* Check if this is a language with variants
|
|
*
|
|
* @since 1.35
|
|
*
|
|
* @return bool
|
|
*/
|
|
public function hasVariants();
|
|
|
|
/**
|
|
* 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
|
|
* @param string $variant
|
|
* @return bool
|
|
*/
|
|
public function hasVariant( $variant );
|
|
|
|
/**
|
|
* Perform output conversion on a string, and encode for safe HTML output.
|
|
*
|
|
* @since 1.35
|
|
*
|
|
* @param string $text Text to be converted
|
|
* @return string string converted to be safely used in HTML
|
|
*/
|
|
public function convertHtml( $text );
|
|
}
|
|
|
|
/** @deprecated class alias since 1.43 */
|
|
class_alias( ILanguageConverter::class, 'ILanguageConverter' );
|