432 lines
18 KiB
PHP
432 lines
18 KiB
PHP
<?php namespace ProcessWire;
|
||
|
||
/**
|
||
* ProcessWire Language Functions
|
||
*
|
||
* #pw-summary-translation Provides GetText-like language translation functions to ProcessWire.
|
||
*
|
||
* ProcessWire 3.x, Copyright 2020 by Ryan Cramer
|
||
* https://processwire.com
|
||
*
|
||
*/
|
||
|
||
/**
|
||
* Perform a language translation
|
||
*
|
||
* This function enables you to specify static text as the argument, and that text becomes translatable (for each language)
|
||
* with ProcessWire’s built-in language translation tools. This function also works just fine if you do not have multi-language
|
||
* support installed, though in that case it just returns the text that it is given.
|
||
*
|
||
* For full documentation, please see the [Code Internationalization (i18n)](https://processwire.com/docs/multi-language-support/code-i18n/)
|
||
* documentation page at ProcessWire.com.
|
||
*
|
||
* This function is very similar to the GNU gettext `_('text');` function and essentially does the same thing, except that it is
|
||
* native to ProcessWire and not using GNU gettext.
|
||
*
|
||
* Use this `__('text')` function for common translations, use the `_x('text', 'context')` function for translations
|
||
* that also require additional context, and use the `_n('singular', 'plural', $n)` function for translations that should
|
||
* changed based on whether a value `$n` would require a singular or plural tense.
|
||
*
|
||
* ### Additional behaviors
|
||
*
|
||
* - You can optionally specify a “textdomain” as the second argument. The textdomain represents the source file of the
|
||
* translation. Most often it would be the current file, so the argument can be omitted, or you can specify `__FILE__`.
|
||
* But in some cases you may want to use a translation from another file, and the textdomain argument enables you to.
|
||
*
|
||
* - When in a class (or module) it is preferable to use `$this->_('text');` rather than `__('text');`, as it is slightly
|
||
* more efficient to do so.
|
||
*
|
||
* - A PHP comment, i.e. `// comment` that appears somewhere after a translation call (on the same line) is used as an
|
||
* additional description for the person translating text. Another comment after that, i.e. `// comment1 // comment2`
|
||
* is used as an additional secondary note for the person translating the text.
|
||
*
|
||
* - It is also possible to provide multiple acceptable phrases for translations, useful when making minor changes to
|
||
* an existing text where you do not want an previous translation to be abandoned. To do so, provide an array argument
|
||
* (using bracket syntax) with the multiple phrases as values, where the first is the newest phrase. This feature was
|
||
* added in ProcessWire 3.0.151. See examples below for usage details.
|
||
*
|
||
* ### Limitations
|
||
*
|
||
* - The function call (and translatable text within it) cannot span more than one line. If your translatable text is long
|
||
* enough to require multiple lines, split them into multiple calls (like one per sentence).
|
||
*
|
||
* - There cannot be more than one `__('text')` function call per line in the PHP code.
|
||
*
|
||
* - The provided text argument must be one string of static text. It cannot contain PHP variables or concatenation. To populate
|
||
* dynamic values you should use PHP’s `sprintf()` (see examples below).
|
||
*
|
||
* ~~~~~~
|
||
* // Standard way to make static text translatable
|
||
* echo __('This is translatable text');
|
||
*
|
||
* // Optionally specify current file as textdomain (same result as above)
|
||
* echo __('This is translatable text', __FILE__);
|
||
*
|
||
* // Specify another file as textdomain (will use translation from that file)
|
||
* echo __('This is translatable text', '/site/templates/_init.php');
|
||
*
|
||
* // Using placeholders to populate dynamic values in translatable text:
|
||
* echo sprintf(__('You are reading the %s page'), $page->title);
|
||
* echo sprintf(__('%d is the current page ID'), $page->id);
|
||
* echo sprintf(__('Today is %1$s and the time is %2$s'), date('l'), date('g:i a'));
|
||
*
|
||
* // Providing a description via PHP comment to translator
|
||
* echo __('Welcome friend!'); // Friendly message for new users
|
||
*
|
||
* // Providing a description AND extra note via PHP comments to translator
|
||
* echo __('Welcome friend!'); // Friendly message for new users // Must be short!
|
||
*
|
||
* // In ProcessWire 3.0.151+ you can change existing phrases without automatically
|
||
* // abandoning the translations for them. To use, include both new and old phrase.
|
||
* // Specify PHP array (bracket syntax required) with 2+ phrases you accept trans-
|
||
* // lations for where the first is the newest/current text to translate. This array
|
||
* // replaces the $text argument of this function. Must be on 1 line.
|
||
* __([ 'New text', 'Old text' ]);
|
||
*
|
||
* // The above can also be used with _x() and _n() calls as well.
|
||
* _x([ 'Canada Goose', 'Canadian Goose' ], 'bird');
|
||
* ~~~~~
|
||
*
|
||
* #pw-group-translation
|
||
*
|
||
* @param string|array|bool $text Text for translation.
|
||
* @param string|array $textdomain Textdomain for the text, may be class name, filename, or something made up by you.
|
||
* If omitted, a debug backtrace will attempt to determine it automatically.
|
||
* @param string|bool|array $context Name of context - DO NOT USE with this function for translation as it will not be parsed for translation.
|
||
* Use only with the `_x()` function, which will be parsed.
|
||
* @return string|array Translated text or original text if translation not available. Returns array only if getting/setting options.
|
||
* @see _x(), _n()
|
||
* @link https://processwire.com/docs/multi-language-support/code-i18n/
|
||
*
|
||
*/
|
||
function __($text, $textdomain = null, $context = '') {
|
||
|
||
static $options = array(
|
||
'entityEncode' => null, // true=always, false=never, 1=only if not already encoded, null=undefined (backwards compatible behavior)
|
||
'translations' => false, // fallback translations to use when live translation not available ['Original text' => 'Translated text']
|
||
'replacements' => false, // global replacements (no textdomain), becomes array once set
|
||
'_useLimit' => null, // internal use: use limit argument for debug_backtrace call
|
||
);
|
||
|
||
$textArray = false;
|
||
$encode = $options['entityEncode'];
|
||
$user = wire('user');
|
||
$language = $user ? $user->get('language') : null; /** @var Language $language */
|
||
|
||
if(!is_string($text)) {
|
||
// getting/setting options or translating with multiple phrases accepted
|
||
if(is_array($text)) {
|
||
// multiple translations accepted for text, with 1st being newest
|
||
$textArray = $text;
|
||
$text = reset($textArray);
|
||
} else if($text === true && $textdomain !== null) {
|
||
// setting (or getting) custom option
|
||
list($option, $values) = array($textdomain, $context);
|
||
if($option === 'replacements' || $option === 'translations') {
|
||
// setting or getting global 'replacements' or 'translations'
|
||
// if not given any values to set then return current value
|
||
if(!is_array($values)) return $options[$option] ? $options[$option] : array();
|
||
// merge with existing 'replacements' or 'translations'
|
||
$options[$option] = $options[$option] === false ? $values : array_merge($options[$option], $values);
|
||
// return current value
|
||
return $options[$option];
|
||
} else if(is_array($option)) {
|
||
// translations options implied by array in $option/$textdomain argument (support legacy behavior)
|
||
return __(true, 'translations', $option);
|
||
} else {
|
||
// set and get other options
|
||
if($option === 'encode') $option = 'entityEncode'; // supported alias
|
||
$currentValue = isset($options[$option]) ? $options[$option] : null; // existing value is returned even when setting
|
||
if($values !== '' && $values !== $currentValue) $options[$option] = $values;
|
||
return $currentValue;
|
||
}
|
||
} else if(is_object($text)) {
|
||
$text = (string) $text;
|
||
} else {
|
||
// unknown custom option
|
||
}
|
||
}
|
||
|
||
// check if global replacement should be used
|
||
if($options['replacements'] !== false && isset($options['replacements'][$text])) {
|
||
$value = $options['replacements'][$text];
|
||
// array for replacement means only apply to named context, ie. 'text' => [ 'replacement', 'context' ]
|
||
if(is_array($value)) $value = isset($value[1]) && $value[1] === $context ? $value[0] : $text;
|
||
// false for $language on the next line ensures the $text value is returned in next if() statement
|
||
if($value !== $text) list($text, $language) = array($value, false);
|
||
}
|
||
|
||
// if multi-language not installed or not available then just return given text
|
||
if(!$language || !wire('languages') || !$language->id) {
|
||
return $encode ? htmlspecialchars($text, ENT_QUOTES, 'UTF-8', $encode === true) : $text;
|
||
}
|
||
|
||
// if _useLimit option not yet defined, define it
|
||
if($options['_useLimit'] === null) {
|
||
$options['_useLimit'] = version_compare(PHP_VERSION, '5.4.0') >= 0;
|
||
}
|
||
|
||
// do we need to determine the textdomain?
|
||
if($textdomain === null) {
|
||
// no specific textdomain provided, so determine automatically
|
||
if($options['_useLimit']) {
|
||
// PHP 5.4.0 or newer
|
||
$traces = @debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 2);
|
||
} else if(defined('DEBUG_BACKTRACE_IGNORE_ARGS')) {
|
||
// PHP 5.3.6 or newer
|
||
$traces = @debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS);
|
||
} else {
|
||
// older PHP (deprecated)
|
||
$traces = @debug_backtrace();
|
||
}
|
||
if(isset($traces[0]) && $traces[0]['file'] != __FILE__) {
|
||
$textdomain = $traces[0]['file'];
|
||
} else if(isset($traces[1]) && $traces[1]['file'] != __FILE__) {
|
||
$textdomain = $traces[1]['file'];
|
||
}
|
||
if(is_null($textdomain)) $textdomain = 'site';
|
||
} else if($textdomain === 'common') {
|
||
// common translation
|
||
$textdomain = 'wire/modules/LanguageSupport/LanguageTranslator.php';
|
||
}
|
||
|
||
// are multiple translatable phrases available in $textArray?
|
||
if($textArray) {
|
||
// translations for multiple phrases accepted (current, previous, etc.)
|
||
$value = null;
|
||
foreach($textArray as $n => $t) {
|
||
$tr = $language->translator()->getTranslation($textdomain, $t, $context);
|
||
if(!$n && $language->isDefault()) {
|
||
$value = strlen($tr) ? $tr : $t;
|
||
break; // default language, do not use alternates
|
||
}
|
||
if($t === $tr || !strlen($tr)) continue; // if not translated, start over
|
||
$value = $tr;
|
||
break;
|
||
}
|
||
if($value === null) $value = $text;
|
||
} else {
|
||
// get translation for single phrase $text
|
||
$value = $language->translator()->getTranslation($textdomain, $text, $context);
|
||
}
|
||
|
||
if($value === "=") {
|
||
// translator has indicated that translated value should be same as source value
|
||
$value = $text;
|
||
} else if($value === "+") {
|
||
// translator has indicated we should use common translation value if available
|
||
$v = $language->translator()->commonTranslation($text);
|
||
$value = empty($v) ? $text : $v;
|
||
} else {
|
||
// regular translation
|
||
// if translated value same as original check if alternate available in pre-defined translations
|
||
if($value === $text && $options['translations'] !== false && isset($options['translations']["$text"])) {
|
||
$value = $options['translations']["$text"];
|
||
// array for translation means only apply to named context, ie. 'old text' => [ 'new text', 'context' ]
|
||
if(is_array($value)) $value = isset($value[1]) && $value[1] === $context ? $value[0] : $text;
|
||
}
|
||
// force original behavior fallback if encode mode not set (i.e. encode when translation available)
|
||
if($encode === null) $encode = 1;
|
||
}
|
||
|
||
if($encode) $value = htmlspecialchars($value, ENT_QUOTES, 'UTF-8', $encode === true);
|
||
|
||
return $value;
|
||
}
|
||
|
||
/**
|
||
* Perform a language translation in a specific context
|
||
*
|
||
* Used when two or more text strings might be the same in default language, but different in other languages.
|
||
* This enables you to limit the context of the translation to a named context, like "button" or "headline" or
|
||
* whatever name you decide to use.
|
||
*
|
||
* ~~~~~
|
||
* echo _x('Click for more', 'button');
|
||
* echo _x('Click for more', 'text-link');
|
||
* ~~~~~
|
||
*
|
||
* #pw-group-translation
|
||
*
|
||
* @param string $text Text for translation.
|
||
* @param string $context Name of context
|
||
* @param string $textdomain Textdomain for the text, may be class name, filename, or something made up by you.
|
||
* If omitted, a debug backtrace will attempt to determine automatically.
|
||
* @return string Translated text or original text if translation not available.
|
||
* @see __(), _n()
|
||
* @link https://processwire.com/docs/multi-language-support/code-i18n/
|
||
*
|
||
*/
|
||
function _x($text, $context, $textdomain = null) {
|
||
return __($text, $textdomain, $context);
|
||
}
|
||
|
||
/**
|
||
* Perform a language translation with singular and plural versions
|
||
*
|
||
* ~~~~~
|
||
* $items = array(...);
|
||
* $qty = count($items);
|
||
* echo _n('Found one item', 'Found multiple items', $qty);
|
||
* echo sprintf(_n('Found one item', 'Found %d items', $qty), $qty);
|
||
* ~~~~~
|
||
*
|
||
* #pw-group-translation
|
||
*
|
||
* @param string $textSingular Singular version of text (when there is 1 item)
|
||
* @param string $textPlural Plural version of text (when there are multiple items or 0 items)
|
||
* @param int $count Quantity of items, should be 0 or more.
|
||
* @param string $textdomain Textdomain for the text, may be class name, filename, or something made up by you.
|
||
* If omitted, a debug backtrace will attempt to determine automatically.
|
||
* @return string Translated text or original text if translation not available.
|
||
* @see __(), _x()
|
||
* @link https://processwire.com/docs/multi-language-support/code-i18n/
|
||
*
|
||
*/
|
||
function _n($textSingular, $textPlural, $count, $textdomain = null) {
|
||
$count = (int) $count;
|
||
if($count === 0 && wire()->languages) {
|
||
$plural = __('0-plural', 'common');
|
||
$value = strtolower($plural) === '0-singular' ? __($textSingular, $textdomain) : __($textPlural, $textdomain);
|
||
} else {
|
||
$value = $count === 1 ? __($textSingular, $textdomain) : __($textPlural, $textdomain);
|
||
}
|
||
return $value;
|
||
}
|
||
|
||
/**
|
||
* Set entity encoding state for language translation function calls
|
||
*
|
||
* The function affects behavior of future `__()`, `_x()` and `_n()` calls.
|
||
*
|
||
* The following can be used for the `$value` argument:
|
||
*
|
||
* - `true` (bool): Entity encoding ON
|
||
* - `false` (bool): Entity encoding OFF
|
||
* - `1` (int): Entity encode only if not already
|
||
* - `null` (null): Entity encoding undefined
|
||
*
|
||
* To get current entity encoding state, call this function with no arguments.
|
||
*
|
||
* #pw-group-translation
|
||
*
|
||
* @param bool|int|string|null $value
|
||
* @return bool|int|string|null
|
||
* @since 3.0.154 Versions 3.0.125 to 3.0.153 can use __(true, 'entityEncode', $value);
|
||
*
|
||
*/
|
||
function wireLangEntityEncode($value = '') {
|
||
return __(true, 'encode', $value);
|
||
}
|
||
|
||
/**
|
||
* Set predefined fallback translation values
|
||
*
|
||
* These predefined translations are used when an existing translation is
|
||
* not available, enabling you to provide translations programmatically.
|
||
*
|
||
* These translations will be used if the text is not translated in the
|
||
* admin. The translations are not specific to any textdomain and thus can
|
||
* serve as a fallback for any file. The array you provide should be
|
||
* associative, where the keys contain the text to translate, and the
|
||
* values contain the translation (see examples).
|
||
*
|
||
* The function affects behavior of future `__()`, `_x()` and `_n()` calls,
|
||
* and their objected-oriented equivalents.
|
||
*
|
||
* ~~~~~
|
||
* // Return 'Hola' when text is 'Hello' and 'Mundo' when text is 'World'
|
||
* if($user->language->name == 'es') {
|
||
* wireLangTranslations([
|
||
* 'Hello' => 'Hola',
|
||
* 'World' => 'Mundo'
|
||
* ]);
|
||
* }
|
||
*
|
||
* // Setting predefined translations with context
|
||
* wireLangTranslations([
|
||
* // would apply only to a _x('Search', 'nav'); call (context)
|
||
* 'Search' => [ 'Buscar', 'nav' ]
|
||
* ]);
|
||
* ~~~~~
|
||
*
|
||
* #pw-group-translation
|
||
*
|
||
* @param array $values
|
||
* @return array
|
||
* @since 3.0.154 Versions 3.0.125 to 3.0.153 can use __(true, array $values);
|
||
*
|
||
*/
|
||
function wireLangTranslations(array $values = array()) {
|
||
return __(true, 'translations', $values);
|
||
}
|
||
|
||
/**
|
||
* Set global translation replacement values
|
||
*
|
||
* This option enables you to replace text sent to translation calls
|
||
* like `__('text')` with your own replacement text. This is similar
|
||
* to the `wireLangTranslations()` function except that it applies
|
||
* regardless of whether or not a translation is available for the
|
||
* phrase. It overrides rather than serves as a fallback.
|
||
*
|
||
* This function works whether ProcessWire multi-language support is
|
||
* installed or not, so it can also be useful for selectively replacing
|
||
* phrases in core or modules.
|
||
*
|
||
* Note that this applies globally to all translations that match,
|
||
* regardless of language. As a result, you would typically surround
|
||
* this in an if() statement to make sure you are in the desired state
|
||
* before you apply the replacements.
|
||
*
|
||
* The function affects behavior of future `__()`, `_x()` and `_n()`
|
||
* calls, as well as their object-oriented equivalents.
|
||
*
|
||
* This function should ideally be called from a /site/init.php file
|
||
* (before PW has booted) to ensure that your replacements will be
|
||
* available to any translation calls. However, it can be called from
|
||
* anywhere you’d like, so long as it is before the translation calls
|
||
* that you are looking to replace.
|
||
*
|
||
* ~~~~~
|
||
* // The following example replaces the labels of all the Tabs in the
|
||
* // Page editor (and anywhere else labels used):
|
||
*
|
||
* wireLangReplacements([
|
||
* 'Content' => 'Data',
|
||
* 'Children' => 'Family',
|
||
* 'Settings' => 'Details',
|
||
* 'Delete' => 'Trash',
|
||
* 'View' => 'See',
|
||
* ]);
|
||
*
|
||
* // If you wanted to be sure the above replacements applied only
|
||
* // to the Page editor, then you would place it in /site/ready.php
|
||
* // or /site/templates/admin.php and surround with an if() statement:
|
||
*
|
||
* if($page->process == 'ProcessPageEdit') {
|
||
* wireLangReplacements([
|
||
* 'Content' => 'Data', // and so on
|
||
* ]);
|
||
* }
|
||
*
|
||
* // To make the replacement apply only for a specific _x() context, specify the
|
||
* // translated value in an array with text first and context second, like the
|
||
* // following example that replaces 'URL' with 'Path' when the context call
|
||
* // specifed 'relative-url' as context, i.e. _x('URL', 'relative-url');
|
||
*
|
||
* wireLangReplacements([
|
||
* 'URL' => [ 'Path', 'relative-url' ],
|
||
* ]);
|
||
* ~~~~~
|
||
*
|
||
* #pw-group-translation
|
||
*
|
||
* @param array $values
|
||
* @return array|string
|
||
* @since 3.0.154
|
||
*
|
||
*/
|
||
function wireLangReplacements(array $values) {
|
||
return __(true, 'replacements', $values);
|
||
}
|