Consistently use '@deprecated since <version>'

[lhc/web/wiklou.git] / languages / Language.php

diff --git a/languages/Language.php b/languages/Language.php
index 320688a..5ef781d 100644 (file)
--- a/languages/Language.php
+++ b/languages/Language.php
@@ -261,7 +261,10 @@ class Language {
         * @since 1.21
         */
        public static function isSupportedLanguage( $code ) {
-               return $code === strtolower( $code ) && is_readable( self::getMessagesFileName( $code ) );
+               return self::isValidBuiltInCode( $code )
+                       && ( is_readable( self::getMessagesFileName( $code ) )
+                               || is_readable( self::getJsonMessagesFileName( $code ) )
+               );
        }
 
        /**
@@ -351,7 +354,7 @@ class Language {
 
        /**
         * Returns true if a language code is of a valid form for the purposes of
-        * internal customisation of MediaWiki, via Messages*.php.
+        * internal customisation of MediaWiki, via Messages*.php or *.json.
         *
         * @param $code string
         *
@@ -477,7 +480,7 @@ class Language {
        /**
         * Same as getFallbacksFor for current language.
         * @return array|bool
-        * @deprecated in 1.19
+        * @deprecated since 1.19
         */
        function getFallbackLanguageCode() {
                wfDeprecated( __METHOD__, '1.19' );
@@ -609,6 +612,7 @@ class Language {
 
        /**
         * Returns gender-dependent namespace alias if available.
+        * See https://www.mediawiki.org/wiki/Manual:$wgExtraGenderNamespaces
         * @param $index Int: namespace index
         * @param $gender String: gender key (male, female... )
         * @return String
@@ -622,8 +626,8 @@ class Language {
        }
 
        /**
-        * Whether this language makes distinguishes genders for example in
-        * namespaces.
+        * Whether this language uses gender-dependent namespace aliases.
+        * See https://www.mediawiki.org/wiki/Manual:$wgExtraGenderNamespaces
         * @return bool
         * @since 1.18
         */
@@ -810,7 +814,7 @@ class Language {
        }
 
        /**
-        * @param  $image
+        * @param $image
         * @return array|null
         */
        function getImageFile( $image ) {
@@ -825,7 +829,7 @@ class Language {
        }
 
        /**
-        * @param  $tog
+        * @param $tog
         * @return string
         */
        function getUserToggle( $tog ) {
@@ -840,7 +844,7 @@ class Language {
         * @param $customisedOnly bool
         *
         * @return array
-        * @deprecated in 1.20, use fetchLanguageNames()
+        * @deprecated since 1.20, use fetchLanguageNames()
         */
        public static function getLanguageNames( $customisedOnly = false ) {
                return self::fetchLanguageNames( null, $customisedOnly ? 'mwfile' : 'mw' );
@@ -853,7 +857,7 @@ class Language {
         * @param $code String Language code.
         * @return Array language code => language name
         * @since 1.18.0
-        * @deprecated in 1.20, use fetchLanguageNames()
+        * @deprecated since 1.20, use fetchLanguageNames()
         */
        public static function getTranslatedLanguageNames( $code ) {
                return self::fetchLanguageNames( $code, 'all' );
@@ -910,12 +914,16 @@ class Language {
                        # We do this using a foreach over the codes instead of a directory
                        # loop so that messages files in extensions will work correctly.
                        foreach ( $returnMw as $code => $value ) {
-                               if ( is_readable( self::getMessagesFileName( $code ) ) ) {
+                               if ( is_readable( self::getMessagesFileName( $code ) )
+                                       || is_readable( self::getJsonMessagesFileName( $code ) )
+                               ) {
                                        $namesMwFile[$code] = $names[$code];
                                }
                        }
+
                        return $namesMwFile;
                }
+
                # 'mw' option; default if it's not one of the other two options (all/mwfile)
                return $returnMw;
        }
@@ -948,7 +956,7 @@ class Language {
         * Only if defined in MediaWiki, no other data like CLDR.
         * @param $code string
         * @return string
-        * @deprecated in 1.20, use fetchLanguageName()
+        * @deprecated since 1.20, use fetchLanguageName()
         */
        function getLanguageName( $code ) {
                return self::fetchLanguageName( $code );
@@ -3075,8 +3083,7 @@ class Language {
         * wfMessage( 'message' )->numParams( $num )->text()
         * </code>
         *
-        * See LanguageGu.php for the Gujarati implementation and
-        * $separatorTransformTable on MessageIs.php for
+        * See $separatorTransformTable on MessageIs.php for
         * the , => . and . => , implementation.
         *
         * @todo check if it's viable to use localeconv() for the decimal
@@ -3584,7 +3591,7 @@ class Language {
        }
        /**
         * Provides an alternative text depending on specified gender.
-        * Usage {{gender:username|masculine|feminine|neutral}}.
+        * Usage {{gender:username|masculine|feminine|unknown}}.
         * username is optional, in which case the gender of current user is used,
         * but only in (some) interface messages; otherwise default gender is used.
         *
@@ -3592,9 +3599,9 @@ class Language {
         * given, it will be returned unconditionally. These details are implied by
         * the caller and cannot be overridden in subclasses.
         *
-        * If more than one form is given, the default is to use the neutral one
-        * if it is specified, and to use the masculine one otherwise. These
-        * details can be overridden in subclasses.
+        * If three forms are given, the default is to use the third (unknown) form.
+        * If fewer than three forms are given, the default is to use the first (masculine) form.
+        * These details can be overridden in subclasses.
         *
         * @param $gender string
         * @param $forms array
@@ -4049,10 +4056,7 @@ class Language {
         * @return string $prefix . $mangledCode . $suffix
         */
        public static function getFileName( $prefix = 'Language', $code, $suffix = '.php' ) {
-               // Protect against path traversal
-               if ( !Language::isValidCode( $code )
-                       || strcspn( $code, ":/\\\000" ) !== strlen( $code )
-               ) {
+               if ( !self::isValidBuiltInCode( $code ) ) {
                        throw new MWException( "Invalid language code \"$code\"" );
                }
 
@@ -4087,6 +4091,21 @@ class Language {
                return $file;
        }
 
+       /**
+        * @param $code string
+        * @return string
+        * @since 1.23
+        */
+       public static function getJsonMessagesFileName( $code ) {
+               global $IP;
+
+               if ( !self::isValidBuiltInCode( $code ) ) {
+                       throw new MWException( "Invalid language code \"$code\"" );
+               }
+
+               return "$IP/languages/i18n/$code.json" ;
+       }
+
        /**
         * @param $code string
         * @return string