3 +--------------------------------------------------------------------+
4 | Copyright CiviCRM LLC. All rights reserved. |
6 | This work is published under the GNU AGPLv3 license with some |
7 | permitted exceptions and without any warranty. For full license |
8 | and copyright information, see https://civicrm.org/licensing |
9 +--------------------------------------------------------------------+
15 * @copyright CiviCRM LLC https://civicrm.org/licensing
20 * Constants for communication preferences.
24 const NONE
= 'none', AUTO
= 'auto';
28 * A callback function which handles SQL string encoding.
29 * Set NULL to use the default, CRM_Core_DAO::escapeString().
30 * This is used by `ts(..., [escape=>sql])`.
32 * This option is not intended for general consumption. It is only intended
33 * for certain pre-boot/pre-install contexts.
35 * You might ask, "Why on Earth does string-translation have an opinion on
36 * SQL escaping?" Good question!
38 public static $SQL_ESCAPER = NULL;
41 * Escape a string if a mode is specified, otherwise return string unmodified.
47 protected static function escape($text, $mode) {
50 if (self
::$SQL_ESCAPER == NULL) {
51 return CRM_Core_DAO
::escapeString($text);
54 return call_user_func(self
::$SQL_ESCAPER, $text);
58 return substr(json_encode($text, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_APOS | JSON_HEX_QUOT
), 1, -1);
64 * A PHP-gettext instance for string translation;
65 * should stay null if the strings are not to be translated (en_US).
68 private $_phpgettext = NULL;
71 * Whether we are using native gettext or not.
74 private $_nativegettext = FALSE;
77 * Gettext cache for extension domains/streamers, depending on if native or phpgettext.
78 * - native gettext: we cache the value for textdomain()
79 * - phpgettext: we cache the file streamer.
82 private $_extensioncache = [];
90 * A locale-based constructor that shouldn't be called from outside of this class (use singleton() instead).
92 * @param string $locale
93 * the base of this certain object's existence.
95 * @return \CRM_Core_I18n
97 public function __construct($locale) {
98 $this->locale
= $locale;
99 if ($locale != '' and $locale != 'en_US') {
100 if (defined('CIVICRM_GETTEXT_NATIVE') && CIVICRM_GETTEXT_NATIVE
&& function_exists('gettext')) {
101 // Note: the file hierarchy for .po must be, for example: l10n/fr_FR/LC_MESSAGES/civicrm.mo
103 $this->_nativegettext
= TRUE;
104 $this->setNativeGettextLocale($locale);
108 // Otherwise, use PHP-gettext
109 $this->setPhpGettextLocale($locale);
114 * Returns whether gettext is running natively or using PHP-Gettext.
117 * True if gettext is native
119 public function isNative() {
120 return $this->_nativegettext
;
124 * Set native locale for getText.
126 * @param string $locale
128 protected function setNativeGettextLocale($locale) {
130 putenv("LANG=$locale");
132 // CRM-11833 Avoid LC_ALL because of LC_NUMERIC and potential DB error.
133 setlocale(LC_TIME
, $locale);
134 setlocale(LC_MESSAGES
, $locale);
135 setlocale(LC_CTYPE
, $locale);
137 bindtextdomain('civicrm', CRM_Core_I18n
::getResourceDir());
138 bind_textdomain_codeset('civicrm', 'UTF-8');
139 textdomain('civicrm');
141 $this->_phpgettext
= new CRM_Core_I18n_NativeGettext();
142 $this->_extensioncache
['civicrm'] = 'civicrm';
146 * Set getText locale.
148 * Since CiviCRM 4.5, expected dir structure is civicrm/l10n/xx_XX/LC_MESSAGES/civicrm.mo
149 * because that is what native gettext expects. Fallback support for the pre-4.5 structure
150 * was removed in CiviCRM 5.51.
152 * CiviCRM 5.23 added support for the CIVICRM_L10N_BASEDIR constant (and [civicrm.l10n])
153 * so that mo files can be stored elsewhere (such as in a web-writable directory, to
154 * support extensions sur as l10nupdate.
156 * @param string $locale
158 protected function setPhpGettextLocale($locale) {
159 require_once 'PHPgettext/streams.php';
160 require_once 'PHPgettext/gettext.php';
162 $mo_file = CRM_Core_I18n
::getResourceDir() . $locale . DIRECTORY_SEPARATOR
. 'LC_MESSAGES' . DIRECTORY_SEPARATOR
. 'civicrm.mo';
163 $streamer = new FileReader($mo_file);
164 $this->_phpgettext
= new gettext_reader($streamer);
165 $this->_extensioncache
['civicrm'] = $this->_phpgettext
;
169 * Return languages available in this instance of CiviCRM.
171 * @param bool $justEnabled
172 * whether to return all languages or just the enabled ones.
175 * Array of code/language name mappings
177 public static function languages($justEnabled = FALSE) {
179 static $enabled = NULL;
182 // Use `getValues`, not `buildOptions` to bypass hook_civicrm_fieldOptions. See core#1132.
183 CRM_Core_OptionValue
::getValues(['name' => 'languages'], $optionValues, 'weight', TRUE);
184 $all = array_column($optionValues, 'label', 'name');
186 // FIXME: How is this not duplicative of the lines above?
190 CRM_Core_OptionValue
::getValues(['name' => 'languages'], $rows);
191 foreach ($rows as $id => $row) {
192 $labels[$row['name']] = $row['label'];
195 // check which ones are available; add them to $all if not there already
197 if (is_dir(CRM_Core_I18n
::getResourceDir()) && $dir = opendir(CRM_Core_I18n
::getResourceDir())) {
198 while ($filename = readdir($dir)) {
199 if (preg_match('/^[a-z][a-z]_[A-Z][A-Z]$/', $filename)) {
200 $codes[] = $filename;
201 if (!isset($all[$filename])) {
202 $all[$filename] = $labels[$filename] ??
"($filename)";
209 // drop the unavailable languages (except en_US)
210 foreach (array_keys($all) as $code) {
211 if ($code == 'en_US') {
214 if (!in_array($code, $codes)) {
222 if ($enabled === NULL) {
223 $languageLimit = Civi
::settings()->get('languageLimit');
225 if ($languageLimit) {
226 foreach ($all as $code => $name) {
227 if (array_key_exists($code, $languageLimit)) {
228 $enabled[$code] = $name;
234 return $justEnabled ?
$enabled : $all;
238 * Get the options available for format locale.
240 * Note the pseudoconstant can't be used as the key is the name not the value.
244 public static function getFormatLocales(): array {
245 $values = CRM_Core_OptionValue
::getValues(['name' => 'languages'], $optionValues, 'label', TRUE);
247 $return[NULL] = ts('Inherit from language');
248 foreach ($values as $value) {
249 $return[$value['name']] = $value['label'];
252 // Hacking in for now since the is probably the most important use-case for
253 // money formatting in an English speaking non-US locale based on any reasonable
255 $return['en_NZ'] = ts('English (New Zealand)');
260 * Return the available UI languages
261 * @return array|string
262 * array(string languageCode => string languageName) if !$justCodes
264 public static function uiLanguages($justCodes = FALSE) {
265 // In multilang we only allow the languages that are configured in db
266 // Otherwise, the languages configured in uiLanguages
267 $settings = Civi
::settings();
268 if (CRM_Core_I18n
::isMultiLingual()) {
269 $codes = array_keys((array) $settings->get('languageLimit'));
272 $codes = $settings->get('uiLanguages');
274 $codes = [$settings->get('lcMessages')];
277 return $justCodes ?
$codes
278 : CRM_Utils_Array
::subset(CRM_Core_I18n
::languages(), $codes);
282 * Replace arguments in a string with their values. Arguments are represented by % followed by their number.
290 public function strarg($str) {
293 for ($i = 1; $i < func_num_args(); $i++
) {
294 $arg = func_get_arg($i);
295 if (is_array($arg)) {
296 foreach ($arg as $aarg) {
297 $tr['%' . ++
$p] = $aarg;
301 $tr['%' . ++
$p] = $arg;
304 return strtr($str, $tr);
308 * Get the directory for l10n resources.
312 public static function getResourceDir() {
313 return CRM_Utils_File
::addTrailingSlash(\Civi
::paths()->getPath('[civicrm.l10n]/.'));
317 * Smarty block function, provides gettext support for smarty.
319 * The block content is the text that should be translated.
321 * Any parameter that is sent to the function will be represented as %n in the translation text,
322 * where n is 1 for the first parameter. The following parameters are reserved:
323 * - escape - sets escape mode:
324 * - 'html' for HTML escaping, this is the default.
325 * - 'js' for javascript escaping.
326 * - 'no'/'off'/0 - turns off escaping
327 * - plural - The plural version of the text (2nd parameter of ngettext())
328 * - count - The item count for plural mode (3rd parameter of ngettext())
329 * - context - gettext context of that string (for homonym handling)
331 * @param string $text
332 * the original string.
333 * @param array $params
334 * The params of the translation (if any).
335 * - domain: string|array a list of translation domains to search (in order)
337 * - skip_translation: flag (do only escape/replacement, skip the actual translation)
340 * the translated string
342 public function crm_translate($text, $params = []) {
343 $escape = $params['escape'] ??
NULL;
344 unset($params['escape']);
346 // sometimes we need to {ts}-tag a string, but don’t want to
347 // translate it in the template (like civicrm_navigation.tpl),
348 // because we handle the translation in a different way (CRM-6998)
349 // in such cases we return early, only doing SQL/JS escaping
350 if (isset($params['skip']) and $params['skip']) {
351 return self
::escape($text, $escape);
354 $plural = $count = NULL;
355 if (isset($params['plural'])) {
356 $plural = $params['plural'];
357 unset($params['plural']);
358 if (isset($params['count'])) {
359 $count = $params['count'];
363 if (isset($params['context'])) {
364 $context = $params['context'];
365 unset($params['context']);
371 if (isset($params['domain'])) {
372 $domain = $params['domain'];
373 unset($params['domain']);
379 $raw = !empty($params['raw']);
380 unset($params['raw']);
382 if (!isset($params['skip_translation'])) {
383 if (!empty($domain)) {
384 // It might be prettier to cast to an array, but this is high-traffic stuff.
385 if (is_array($domain)) {
386 foreach ($domain as $d) {
387 $candidate = $this->crm_translate_raw($text, $d, $count, $plural, $context);
388 if ($candidate != $text) {
395 $text = $this->crm_translate_raw($text, $domain, $count, $plural, $context);
399 $text = $this->crm_translate_raw($text, NULL, $count, $plural, $context);
403 // replace the numbered %1, %2, etc. params if present
404 if (count($params) && !$raw) {
405 $text = $this->strarg($text, $params);
408 return self
::escape($text, $escape);
412 * Lookup the raw translation of a string (without any extra escaping or interpolation).
414 * @param string $text
415 * @param string|null $domain
416 * @param int|null $count
417 * @param string $plural
418 * @param string $context
422 protected function crm_translate_raw($text, $domain, $count, $plural, $context) {
423 // gettext domain for extensions
424 $domain_changed = FALSE;
425 if (!empty($domain) && $this->_phpgettext
) {
426 if ($this->setGettextDomain($domain)) {
427 $domain_changed = TRUE;
431 // do all wildcard translations first
433 $stringTable = $this->getWordReplacements();
436 if (isset($stringTable['enabled']['exactMatch'])) {
437 foreach ($stringTable['enabled']['exactMatch'] as $search => $replace) {
438 if ($search === $text) {
448 isset($stringTable['enabled']['wildcardMatch'])
450 $search = array_keys($stringTable['enabled']['wildcardMatch']);
451 $replace = array_values($stringTable['enabled']['wildcardMatch']);
452 $text = str_replace($search, $replace, $text);
455 // dont translate if we've done exactMatch already
457 // use plural if required parameters are set
458 if (isset($count) && isset($plural)) {
460 if ($this->_phpgettext
) {
461 $text = $this->_phpgettext
->ngettext($text, $plural, (int) $count);
464 // if the locale's not set, we do ngettext work by hand
465 // if $count == 1 then $text = $text, else $text = $plural
471 // expand %count in translated string to $count
472 $text = strtr($text, ['%count' => $count]);
474 // if not plural, but the locale's set, translate
476 elseif ($this->_phpgettext
) {
478 $text = $this->_phpgettext
->pgettext($context, $text);
481 $text = $this->_phpgettext
->translate($text);
486 if ($domain_changed) {
487 $this->setGettextDomain('civicrm');
494 * Translate a string to the current locale.
496 * @param string $string
497 * this string should be translated.
500 * the translated string
502 public function translate($string) {
503 return ($this->_phpgettext
) ?
$this->_phpgettext
->translate($string) : $string;
507 * Localize (destructively) array values.
509 * @param array $array
510 * the array for localization (in place).
511 * @param array $params
512 * an array of additional parameters.
514 public function localizeArray(
518 $tsLocale = CRM_Core_I18n
::getLocale();
520 if ($tsLocale == 'en_US') {
524 foreach ($array as & $value) {
526 $value = ts($value, $params);
532 * Localize (destructively) array elements with keys of 'title'.
534 * @param array $array
535 * the array for localization (in place).
537 public function localizeTitles(&$array) {
538 foreach ($array as $key => $value) {
539 if (is_array($value)) {
540 $this->localizeTitles($value);
541 $array[$key] = $value;
543 elseif ((string ) $key == 'title') {
544 $array[$key] = ts($value, ['context' => 'menu']);
550 * Binds a gettext domain, wrapper over bindtextdomain().
553 * Key of the extension (can be 'civicrm', or 'org.example.foo').
556 * True if the domain was changed for an extension.
558 public function setGettextDomain($key) {
559 /* No domain changes for en_US */
560 if (!$this->_phpgettext
) {
564 // It's only necessary to find/bind once
565 if (!isset($this->_extensioncache
[$key])) {
567 $mapper = CRM_Extension_System
::singleton()->getMapper();
568 $path = $mapper->keyToBasePath($key);
569 $info = $mapper->keyToInfo($key);
570 $domain = $info->file
;
572 if ($this->_nativegettext
) {
573 bindtextdomain($domain, $path . DIRECTORY_SEPARATOR
. 'l10n');
574 bind_textdomain_codeset($domain, 'UTF-8');
575 $this->_extensioncache
[$key] = $domain;
579 $mo_file = $path . DIRECTORY_SEPARATOR
. 'l10n' . DIRECTORY_SEPARATOR
. $this->locale
. DIRECTORY_SEPARATOR
. 'LC_MESSAGES' . DIRECTORY_SEPARATOR
. $domain . '.mo';
580 $streamer = new FileReader($mo_file);
581 $this->_extensioncache
[$key] = $streamer->length() ?
new gettext_reader($streamer) : NULL;
584 catch (CRM_Extension_Exception
$e) {
585 // Intentionally not translating this string to avoid possible infinite loops
586 // Only developers should see this string, if they made a mistake in their ts() usage.
587 CRM_Core_Session
::setStatus('Unknown extension key in a translation string: ' . $key, '', 'error');
588 $this->_extensioncache
[$key] = FALSE;
592 if (isset($this->_extensioncache
[$key]) && $this->_extensioncache
[$key]) {
593 if ($this->_nativegettext
) {
594 textdomain($this->_extensioncache
[$key]);
597 $this->_phpgettext
= $this->_extensioncache
[$key];
607 * Is the current CiviCRM domain in multilingual mode.
610 * True if CiviCRM is in multilingual mode.
612 public static function isMultilingual() {
613 $domain = CRM_Core_BAO_Domain
::getDomain();
614 return (bool) $domain->locales
;
618 * Returns languages if domain is in multilingual mode.
622 public static function getMultilingual() {
623 $domain = CRM_Core_BAO_Domain
::getDomain();
624 return $domain->locales ? CRM_Core_DAO
::unSerializeField($domain->locales
, CRM_Core_DAO
::SERIALIZE_SEPARATOR_TRIMMED
) : FALSE;
628 * Is the language written "right-to-left"?
630 * @param string $language
631 * Language (for example 'en_US', or 'fr_CA').
634 * True if it is an RTL language.
636 public static function isLanguageRTL($language) {
637 $rtl = CRM_Core_I18n_PseudoConstant
::getRTLlanguages();
638 $short = CRM_Core_I18n_PseudoConstant
::shortForLong($language);
640 return (in_array($short, $rtl));
644 * If you switch back/forth between locales/drivers, it may be necessary
645 * to reset some options.
647 protected function reactivate() {
648 if ($this->_nativegettext
) {
649 $this->setNativeGettextLocale($this->locale
);
655 * Change the processing language without changing the current user language
657 * @param string $locale
658 * Locale (for example 'en_US', or 'fr_CA').
659 * True if the domain was changed for an extension.
661 public function setLocale($locale) {
663 // Change the language of the CMS as well, for URLs.
664 CRM_Utils_System
::setUFLocale($locale);
666 // For sql queries, if running in DB multi-lingual mode.
670 $dbLocale = "_{$locale}";
673 // For self::getLocale()
677 CRM_Core_I18n
::singleton()->reactivate();
681 * Static instance provider - return the instance for the current locale.
683 * @return CRM_Core_I18n
685 public static function &singleton() {
686 if (!isset(Civi
::$statics[__CLASS__
]['singleton'])) {
687 Civi
::$statics[__CLASS__
]['singleton'] = [];
689 $tsLocale = CRM_Core_I18n
::getLocale();
690 if (!isset(Civi
::$statics[__CLASS__
]['singleton'][$tsLocale])) {
691 Civi
::$statics[__CLASS__
]['singleton'][$tsLocale] = new CRM_Core_I18n($tsLocale);
694 return Civi
::$statics[__CLASS__
]['singleton'][$tsLocale];
698 * Set the LC_TIME locale if it's not set already (for a given language choice).
701 * the final LC_TIME that got set
703 public static function setLcTime() {
704 static $locales = [];
706 $tsLocale = CRM_Core_I18n
::getLocale();
707 if (!isset($locales[$tsLocale])) {
708 // with the config being set to pl_PL: try pl_PL.UTF-8,
709 // then pl_PL, if neither present fall back to C
710 $locales[$tsLocale] = setlocale(LC_TIME
, $tsLocale . '.UTF-8', $tsLocale, 'C');
713 return $locales[$tsLocale];
717 * Get the default language for contacts where no language is provided.
719 * Note that NULL is a valid option so be careful with checking for empty etc.
721 * NULL would mean 'we don't know & we don't want to hazard a guess'.
725 public static function getContactDefaultLanguage() {
726 $language = Civi
::settings()->get('contact_default_language');
727 if ($language == 'undefined') {
730 if (empty($language) ||
$language === '*default*') {
731 $language = civicrm_api3('setting', 'getvalue', [
732 'name' => 'lcMessages',
733 'group' => CRM_Core_BAO_Setting
::LOCALIZATION_PREFERENCES_NAME
,
736 elseif ($language == 'current_site_language') {
737 return CRM_Core_I18n
::getLocale();
744 * Get the current locale
748 public static function getLocale() {
750 return $tsLocale ?
$tsLocale : 'en_US';
755 * Ex: $stringTable['enabled']['wildcardMatch']['foo'] = 'bar';
757 private function getWordReplacements() {
758 if (isset(Civi
::$statics['testPreInstall'])) {
762 // FIXME: Is there a constant we can reference instead of hardcoding en_US?
763 $replacementsLocale = $this->locale ?
$this->locale
: 'en_US';
764 if ((!isset(Civi
::$statics[__CLASS__
]) ||
!array_key_exists($replacementsLocale, Civi
::$statics[__CLASS__
]))) {
765 if (defined('CIVICRM_DSN') && !CRM_Core_Config
::isUpgradeMode()) {
766 Civi
::$statics[__CLASS__
][$replacementsLocale] = CRM_Core_BAO_WordReplacement
::getLocaleCustomStrings($replacementsLocale);
769 Civi
::$statics[__CLASS__
][$replacementsLocale] = [];
772 return Civi
::$statics[__CLASS__
][$replacementsLocale];
778 * Short-named function for string translation, defined in global scope so it's available everywhere.
780 * @param string $text
781 * String string for translating.
782 * @param array $params
783 * Array an array of additional parameters.
786 * the translated string
788 function ts($text, $params = []) {
789 static $bootstrapReady = FALSE;
790 static $lastLocale = NULL;
792 static $function = NULL;
798 // When the settings become available, lookup customTranslateFunction.
799 if (!$bootstrapReady) {
800 $bootstrapReady = (bool) \Civi\Core\Container
::isContainerBooted();
801 if ($bootstrapReady) {
802 // just got ready: determine whether there is a working custom translation function
803 $config = CRM_Core_Config
::singleton();
804 if (isset($config->customTranslateFunction
) and function_exists($config->customTranslateFunction
)) {
805 $function = $config->customTranslateFunction
;
810 $activeLocale = CRM_Core_I18n
::getLocale();
811 if (!$i18n or $lastLocale != $activeLocale) {
812 $i18n = CRM_Core_I18n
::singleton();
813 $lastLocale = $activeLocale;
817 return $function($text, $params);
820 return $i18n->crm_translate($text, $params);