<?php
/**
* Represents a WordPress locale
*
* @property string $lang
* @property string $region
* @property string $variant
*/
class Loco_Locale implements JsonSerializable {
/**
* Language subtags
* @var string[]
*/
private array $tag;
/**
* Cached composite tag
*/
private ?string $_tag = null;
/**
* Cached icon css class
*/
private ?string $icon = null;
/**
* Name in English
*/
private string $name = '';
/**
* Name in language of self
*/
private ?string $_name = null;
/**
* Plural equation expressed in terms of "n"
*/
private string $pluraleq;
/**
* Cache of plural forms mapped optionally to CLDR mnemonic tags
*/
private ?array $plurals = null;
/**
* Validity cache
*/
private ?bool $valid = null;
/**
* @param string $tag Full language tag
*/
public static function parse( string $tag ):self {
$locale = new Loco_Locale('');
try {
$locale->setSubtags( loco_parse_wp_locale($tag) );
}
catch( Exception $e ){
// isValid should return false
}
do_action( 'loco_parse_locale', $locale, $tag );
return $locale;
}
/**
* Construct from subtags NOT from composite tag. See self::parse
* Note that this skips normalization and validation steps
*/
public function __construct( string $lang = '', string $region = '', string $variant = '' ){
if( 1 == func_num_args() && isset($lang[3]) ){
throw new BadMethodCallException('Did you mean Loco_Locale::parse('.var_export($lang,1).') ?');
}
$this->tag = compact('lang','region','variant');
}
/**
* Allow read access to subtags
* @internal
* @param string $t subtag
* @return string
*/
public function __get( $t ){
return $this->tag[ $t ] ?? '';
}
/**
* Allow write access to subtags
* @internal
* @param string $t subtag, e.g. "lang"
* @param string $s subtag value, e.g. "en"
* @return void
*/
public function __set( $t, $s ){
if( isset($this->tag[$t]) ){
$this->tag[$t] = $s;
$this->setSubtags( $this->tag );
}
}
/**
* Set subtags as produced from loco_parse_wp_locale
* @param string[] $tag
*/
public function setSubtags( array $tag ):self {
$this->valid = false;
$default = [ 'lang' => '', 'region' => '', 'variant' => '' ];
// disallow setting of unsupported tags
if( $bad = array_diff_key($tag, $default) ){
throw new Loco_error_LocaleException('Unsupported subtags: '.implode(',',$bad) );
}
$tag += $default;
// language tag is minimum requirement
if( ! $tag['lang'] ){
throw new Loco_error_LocaleException('Locale must have a language');
}
// no UN codes in WordPress
if( preg_match('/^\\d+$/',$tag['region']) ){
throw new Loco_error_LocaleException('Numeric regions not supported');
}
// non-standard variant code. e.g. formal/informal
if( is_array($tag['variant']) ){
$tag['variant'] = implode('_',$tag['variant']);
}
// normalize case
$tag['lang'] = strtolower($tag['lang']);
$tag['region'] = strtoupper($tag['region']);
$tag['variant'] = strtolower($tag['variant']);
// set subtags and invalidate cache of language tag
$this->tag = $tag;
$this->_tag = null;
$this->icon = null;
$this->valid = true;
return $this;
}
/**
* Ensure correct casing of subtags
*/
public function normalize():self {
try {
$this->setSubtags( $this->tag );
}
catch( Loco_error_LocaleException $e ){
$this->_tag = '';
$this->icon = null;
$this->name = 'Invalid locale';
$this->_name = null;
}
return $this;
}
/**
* @return string
*/
public function __toString(){
$str = $this->_tag;
if( is_null($str) ){
$str = implode('_',array_filter($this->tag));
$this->_tag = $str;
}
return $str;
}
/**
* @param bool $translate whether to get name in current display language
*/
public function getName( bool $translate = true ):?string{
$name = $this->name;
// use canonical native name only when current language matches
// deliberately not matching whole tag such that fr_CA would show native name of fr_FR
if( $translate ){
$locale = self::parse( function_exists('get_user_locale') ? get_user_locale() : get_locale() );
if( $this->lang === $locale->lang && $this->_name ){
$name = $this->_name;
}
/*/ Note that no dynamic translation of English name is performed, but can be filtered with loco_parse_locale
else {
$name = __($name,'loco-translate-languages');
}*/
}
if( is_string($name) && '' !== $name ){
return $name;
}
return null;
}
/**
* Get canonical native name as defined by WordPress
*/
public function getNativeName():?string {
$name = $this->_name;
if( is_string($name) && '' !== $name ){
return $name;
}
return null;
}
/**
* Get CSS class for locale icon
*/
public function getIcon(): ?string {
$icon = $this->icon;
if( is_null($icon) ){
$tag = [];
if( ! $this->tag['lang'] ){
$tag[] = 'lang lang-zxx';
}
foreach( $this->tag as $class => $code ){
if( $code ){
$tag[] = $class.' '.$class.'-'.$code;
}
}
$icon = strtolower( implode(' ',$tag) );
$this->icon = $icon;
}
return $icon;
}
/**
* Force custom icon, or reset. Used in tests.
*/
public function setIcon( string $css ):self {
$this->icon = $css ?: null;
return $this;
}
/**
* Set custom locale name, and optional translation
*/
public function setName( string $english_name, string $native_name = '' ):self {
$this->name = apply_filters('loco_locale_name', $english_name, $native_name );
$this->_name = $native_name ?: null;
return $this;
}
/**
* Test whether locale is valid
*/
public function isValid():bool {
if( is_null($this->valid) ){
$this->normalize();
}
return $this->valid;
}
/**
* Resolve this locale's "official" name from WordPress's translation api
* @return string English name currently set
*/
public function fetchName( Loco_api_WordPressTranslations $api ): ?string {
$tag = (string) $this;
// pull from WordPress translations API if network allowed
$locale = $api->getLocale($tag);
if( $locale ){
$this->setName( $locale->getName(false), $locale->getNativeName() );
}
return $this->getName(false);
}
/**
* Resolve this locale's name from compiled Loco data
* @return string English name currently set
*/
public function buildName(): ?string {
// should at least have a language or not valid
if( $this->isValid() ){
$code = $this->tag['lang'];
$db = Loco_data_CompiledData::get('languages');
if( $name = $db[$code] ){
// if variant is present add only that in brackets (no lookup required)
if( $code = $this->tag['variant'] ){
$name .= ' ('.ucfirst($code).')';
}
// else add region in brackets if present
else if( $code = $this->tag['region'] ){
$db = Loco_data_CompiledData::get('regions');
if( $extra = $db[$code] ){
$name .= ' ('.$extra.')';
}
else {
$name .= ' ('.$code.')';
}
}
$this->setName( $name );
}
}
else {
$this->setName( __('Invalid locale','loco-translate') );
}
return $this->getName();
}
/**
* Ensure locale has a label, even if it has to fall back to language code or error
*/
public function ensureName( Loco_api_WordPressTranslations $api ):string {
$name = $this->getName();
if( ! $name ){
$name = $this->fetchName($api);
// failing that, build own name from components
if( ! $name ){
$name = $this->buildName();
// last resort, use tag as name
if( ! $name ){
$name = (string) $this;
$this->setName( $name );
}
}
}
return $name;
}
#[ReturnTypeWillChange]
public function jsonSerialize():array{
$a = $this->tag;
$a['label'] = $this->getName();
// plural data expected by editor
$p = $this->getPluralData();
$a['pluraleq'] = $p[0];
$a['nplurals'] = count($p[1]);
$a['plurals'] = $this->getPluralForms();
// tone setting may be used by some external translation providers
$a['tone'] = $this->getFormality();
return $a;
}
private function getPluralData():array {
if( is_null($this->plurals) ){
$lc = strtolower($this->lang);
$db = Loco_data_CompiledData::get('plurals');
$id = $lc && isset($db[$lc]) ? $db[$lc] : 0;
list( $this->pluraleq, $this->plurals ) = $db[''][$id];
}
return [ $this->pluraleq, $this->plurals ];
}
/**
* Get translated plural form labels
* @return string[]
*/
public function getPluralForms(): array {
list( , $plurals ) = $this->getPluralData();
$nplurals = count($plurals);
// Languages with no plural forms, where n always yields 0. The UI doesn't show a label for this.
if( 1 === $nplurals ){
return [ 'All' ];
}
// Germanic plurals can show singular/plural as per source string text boxes
// Note that french style plurals include n=0 under the "Single", but we will show "Single (0,1)"
if( 2 === $nplurals ){
$l10n = [
'one' => _x('Single','Editor','loco-translate'),
'other' => _x('Plural',"Editor",'loco-translate'),
];
}
// else translate all implemented plural forms and show sample numbers if useful:
// for meaning of categories, see http://cldr.unicode.org/index/cldr-spec/plural-rules
else {
$l10n = [
// Translators: Plural category for zero quantity
'zero' => _x('Zero','Plural category','loco-translate'),
// Translators: Plural category for singular quantity
'one' => _x('One','Plural category','loco-translate'),
// Translators: Plural category used in some multi-plural languages
'two' => _x('Two','Plural category','loco-translate'),
// Translators: Plural category used in some multi-plural languages
'few' => _x('Few','Plural category','loco-translate'),
// Translators: Plural category used in some multi-plural languages
'many' => _x('Many','Plural category','loco-translate'),
// Translators: General plural category not covered by other forms
'other' => _x('Other','Plural category','loco-translate'),
];
}
// process labels to be shown in editor tab, appending sample values of `n` if useful
$labels = [];
foreach( $plurals as $sample => $tag ){
if( is_int($sample) ){
$sample = sprintf('%u',$sample);
}
// if CLDR tag is to be used we'll need to translate it
if( array_key_exists($tag,$l10n) ){
$name = $l10n[$tag];
}
else {
$name = $tag;
}
// show just samples if no name
if( '' === $name ){
$labels[] = $sample;
}
// show just name if label is numeric, or samples are redundant
else if(
preg_match('/\\d/',$name) ||
( 'one' === $tag && '1' === $sample ) ||
( 'two' === $tag && '2' === $sample ) ||
( 'zero' === $tag && '0' === $sample ) ||
( 'other' === $tag && 2 === $nplurals )
){
$labels[] = $name;
}
// else both - most common for standard CLDR forms
else {
$labels[] = sprintf('%s (%s)', $name, $sample );
}
}
return $labels;
}
/**
* Get PO style Plural-Forms header value comprising number of forms and integer equation for n
*/
public function getPluralFormsHeader(): string {
list( $equation, $forms ) = $this->getPluralData();
return sprintf('nplurals=%u; plural=%s;', count($forms), $equation );
}
/**
* Apply PO style Plural-Forms header.
* @param string $str header value e.g. "nplurals=2; plural=n != 1;"
* @return void
*/
public function setPluralFormsHeader( string $str ){
if( ! preg_match('#^nplurals=(\\d);\\s*plural=([-+/*%!=<>|&?:()n\\d ]+);?$#', $str, $match ) ){
throw new InvalidArgumentException('Invalid Plural-Forms header, '.json_encode($str) );
}
$nplurals = (int) $match[1];
$pluraleq = trim( $match[2],' ');
// single form requires no further inspection
if( 2 > $nplurals ){
$this->pluraleq = '0';
$this->plurals = ['other'];
return;
}
// Override new equation in all cases
$previous = $this->getPluralData()[0];
$this->pluraleq = $pluraleq;
// quit asap if plural forms being set aren't changing anything
if( $nplurals === count($this->plurals) && self::hashPlural($previous) === self::hashPlural($pluraleq) ){
return;
}
// compile sample keys as per built-in CLDR rule for this language
$keys = [];
$formula = new Plural_Forms($pluraleq);
$ns = [0,1,2,3,4,5,6,7,8,9,10,11,12,13,20,21,22,30,31,32,100,101,102,103,104,111,200,201,202,301,302];
for( $i = 0; $i < $nplurals; $i++ ){
$sample = [];
$suffix = '';
foreach( $ns as $j => $n ){
if( is_null($n) || $formula->execute($n) !== $i ){
continue;
}
$ns[$j] = null;
if( array_key_exists(2,$sample) ){
$suffix = "\xE2\x80\xA6";
break;
}
else {
$sample[] = $n;
}
}
$keys[] = implode(',',$sample).$suffix;
}
// cast to string for comparison due to PHP forcing integer keys in this->plurals
$expect = implode('|',$keys);
$actual = implode('|',array_keys($this->plurals));
// use mnemonic tags only if they match the default (CLDR) tags for the current language
if( $expect !== $actual ){
// exception when two forms only and the first accepts n=1 and second n=2
if( 2 === $nplurals && 0 === $formula->execute(1) && 1 === $formula->execute(2) ){
$tags = ['one','other'];
}
// blanking CLDR tags means only samples will be used as labels
else {
$tags = array_fill(0,$nplurals,'');
// Translators: Shown when a PO file's Plural-Forms header has a different formula from the Unicode CLDR rules
Loco_error_AdminNotices::info( __('Plural forms differ from Loco Translate\'s built in rules for this language','loco-translate') );
}
// set new plural forms
$this->plurals = array_combine($keys,$tags);
}
}
/**
* Crude normalizer for a plural equation such that similar formulae can be compared.
* @param string $str original plural equation
* @return string signature for comparison
*/
private static function hashPlural( string $str ):string {
return trim( str_replace([' ','<>'],['','!='],$str), '()' );
}
/**
* Get formality setting, whether implied or explicit.
* @return string either "", "formal" or "informal"
*/
public function getFormality():string {
$value = '';
$tag = $this->__toString();
$variant = $this->variant;
if( '' === $variant ){
// if a formal variant exists, tone may be implied informal
$d = Loco_data_CompiledData::get('locales');
if( $d->offsetExists($tag.'_formal') ){
if( ! $d->offsetExists($tag.'_informal') ) {
$value = 'informal';
}
}
// if an informal variant exists, tone may be implied formal
else if( $d->offsetExists($tag.'_informal') ){
if( ! $d->offsetExists($tag.'_formal') ) {
$value = 'formal';
}
}
}
else if( 'formal' === $variant || 'informal' === $variant ){
$value = $variant;
}
return apply_filters('loco_locale_formality',$value,$tag);
}
}
// Depends on compiled library
if( ! function_exists('loco_parse_wp_locale') ){
loco_require_lib('compiled/locales.php');
}