(REF) ts() - Move from class-file to functions.php

Overview
--------

`ts()` is a global helper function. This normalizes the way it loads.

Before
------

`ts()` is defined in `CRM/Core/I18n.php`, which is most intuitively
understood as a class-file.  As a class-file, you would expect it do one
thing (declare `CRM_Core_I18n`) and to load via auto-loader.

In fact, the file does two things: declare `CRM_Core_I18n` and declare
global function `ts()`.  For this latter reason, the system is sprinkled
with calls to `require_once CRM/Core/I18n.php`. Presumably, folks needed
to ensure that `ts()` was defined/parsed early... but didn't actually have
a use for calling the class.

After
-----

Follow [this composer convention](https://getcomposer.org/doc/04-schema.md#files).

The global function is declared in a separate file.  This file is loaded
very early (whenever the autolaoder is registered). The pattern means
that `ts()` is implicitly available.

Of course, if you need `CRM_Core_I18n`, it can still be resolved via autoloader.

CRM/Core/I18n.php

@@ -792,71 +792,3 @@ private function getWordReplacements() {
   }
 
 }
-
-/**
- * Short-named function for string translation, defined in global scope so it's available everywhere.
- *
- * @param string $text
- *   String for translating.
- *   Ex: 'Hello, %1!'
- * @param array $params
- *   An array of additional parameters, as per `crm_translate()`.
- *   Ex: [1 => 'Dave']
- * @return string
- *   The translated string
- *   Ex: '¡Buenos días Dave!`
- * @see \CRM_Core_I18n::crm_translate()
- */
-function ts($text, $params = []) {
-  static $bootstrapReady = FALSE;
-  static $lastLocale = NULL;
-  static $i18n = NULL;
-  static $function = NULL;
-
-  if ($text == '') {
-    return '';
-  }
-
-  // When the settings become available, lookup customTranslateFunction.
-  if (!$bootstrapReady) {
-    $bootstrapReady = (bool) \Civi\Core\Container::isContainerBooted();
-    if ($bootstrapReady) {
-      // just got ready: determine whether there is a working custom translation function
-      $config = CRM_Core_Config::singleton();
-      if (!empty($config->customTranslateFunction) && function_exists($config->customTranslateFunction)) {
-        $function = $config->customTranslateFunction;
-      }
-    }
-  }
-
-  $civicrmLocale = CRM_Core_I18n::getLocale();
-  if (!$i18n or $lastLocale != $civicrmLocale) {
-    $i18n = CRM_Core_I18n::singleton();
-    $lastLocale = $civicrmLocale;
-  }
-
-  if ($function) {
-    return $function($text, $params);
-  }
-  else {
-    return $i18n->crm_translate($text, $params);
-  }
-}
-
-/**
- * Alternate name for `ts()`
- *
- * This is functionally equivalent to `ts()`. However, regular `ts()` is subject to extra linting
- * rules. Using `_ts()` can bypass the linting rules for the rare cases where you really want
- * special/dynamic values.
- *
- * @param array ...$args
- * @return string
- * @see ts()
- * @see \CRM_Core_I18n::crm_translate()
- * @internal
- */
-function _ts(...$args) {
-  $f = 'ts';
-  return $f(...$args);
-}

composer.json

@@ -35,6 +35,7 @@
       "Civi\\": [".", "Civi/", "setup/src/"]
     },
     "files": [
+      "functions.php",
       "guzzle_php81_shim.php"
     ]
   },

distmaker/dists/common.sh

@@ -87,7 +87,7 @@ function dm_install_core() {
   done
 
   dm_install_files "$repo" "$to" {agpl-3.0,agpl-3.0.exception,gpl}.txt
-  dm_install_files "$repo" "$to" composer.json composer.lock package.json Civi.php README.md release-notes.md extension-compatibility.json deleted-files-list.json guzzle_php81_shim.php
+  dm_install_files "$repo" "$to" composer.json composer.lock package.json Civi.php functions.php README.md release-notes.md extension-compatibility.json deleted-files-list.json guzzle_php81_shim.php
 
   mkdir -p "$to/sql"
   pushd "$repo" >> /dev/null

functions.php

@@ -0,0 +1,86 @@
+<?php
+
+/*
+ +--------------------------------------------------------------------+
+ | Copyright CiviCRM LLC. All rights reserved.                        |
+ |                                                                    |
+ | This work is published under the GNU AGPLv3 license with some      |
+ | permitted exceptions and without any warranty. For full license    |
+ | and copyright information, see https://civicrm.org/licensing       |
+ +--------------------------------------------------------------------+
+ */
+
+/**
+ * @file
+ *
+ * CiviCRM is generally organized around classes, but there are a handful of global functions.
+ * Declare them here.
+ */
+
+/**
+ * Short-named function for string translation, defined in global scope so it's available everywhere.
+ *
+ * @param string $text
+ *   String for translating.
+ *   Ex: 'Hello, %1!'
+ * @param array $params
+ *   An array of additional parameters, as per `crm_translate()`.
+ *   Ex: [1 => 'Dave']
+ * @return string
+ *   The translated string
+ *   Ex: '¡Buenos días Dave!`
+ * @see \CRM_Core_I18n::crm_translate()
+ */
+function ts($text, $params = []) {
+  static $bootstrapReady = FALSE;
+  static $lastLocale = NULL;
+  static $i18n = NULL;
+  static $function = NULL;
+
+  if ($text == '') {
+    return '';
+  }
+
+  // When the settings become available, lookup customTranslateFunction.
+  if (!$bootstrapReady) {
+    $bootstrapReady = (bool) \Civi\Core\Container::isContainerBooted();
+    if ($bootstrapReady) {
+      // just got ready: determine whether there is a working custom translation function
+      $config = CRM_Core_Config::singleton();
+      if (!empty($config->customTranslateFunction) && function_exists($config->customTranslateFunction)) {
+        $function = $config->customTranslateFunction;
+      }
+    }
+  }
+
+  $civicrmLocale = CRM_Core_I18n::getLocale();
+  if (!$i18n or $lastLocale != $civicrmLocale) {
+    $i18n = CRM_Core_I18n::singleton();
+    $lastLocale = $civicrmLocale;
+  }
+
+  if ($function) {
+    return $function($text, $params);
+  }
+  else {
+    return $i18n->crm_translate($text, $params);
+  }
+}
+
+/**
+ * Alternate name for `ts()`
+ *
+ * This is functionally equivalent to `ts()`. However, regular `ts()` is subject to extra linting
+ * rules. Using `_ts()` can bypass the linting rules for the rare cases where you really want
+ * special/dynamic values.
+ *
+ * @param array ...$args
+ * @return string
+ * @see ts()
+ * @see \CRM_Core_I18n::crm_translate()
+ * @internal
+ */
+function _ts(...$args) {
+  $f = 'ts';
+  return $f(...$args);
+}