Ticket #41305: 41305.implementation

diff --git src/wp-includes/l10n.php src/wp-includes/l10n.php
index a81470ff7d..917e402ec8 100644
--- src/wp-includes/l10n.php
+++ src/wp-includes/l10n.php
@@ -203,6 +203,24 @@ function __( $text, $domain = 'default' ) {
 }
 
 /**
+ * Lazily retrieves the translation of $text.
+ *
+ * If there is no translation, or the text domain isn't loaded, the original
+ * text is returned.
+ *
+ * @since 4.9.0
+ *
+ * @param string $text   Text to translate.
+ * @param string $domain Optional. Text domain. Unique identifier for
+ *                       retrieving translated strings. Default 'default'.
+ *
+ * @return WP_String_Proxy Proxy object representing a string.
+ */
+function _l( $text, $domain = 'default' ) {
+       return new WP_Translation_Proxy( $text, $domain );
+}
+
+/**
  * Retrieve the translation of $text and escapes it for safe use in an attribute.
  *
  * If there is no translation, or the text domain isn't loaded, the original text is returned.
@@ -219,6 +237,27 @@ function esc_attr__( $text, $domain = 'default' ) {
 }
 
 /**
+ * Lazily retrieve the translation of $text and escape it for safe use in an
+ * attribute.
+ *
+ * If there is no translation, or the text domain isn't loaded, the original
+ * text is returned.
+ *
+ * @since 4.9.0
+ *
+ * @param string $text   Text to translate.
+ * @param string $domain Optional. Text domain. Unique identifier for
+ *                       retrieving translated strings. Default 'default'.
+ *
+ * @return WP_String_Proxy Proxy object representing a string.
+ */
+function esc_attr_l( $text, $domain = 'default' ) {
+       return new WP_Escape_Attribute_Proxy(
+               new WP_Translation_Proxy( $text, $domain )
+       );
+}
+
+/**
  * Retrieve the translation of $text and escapes it for safe use in HTML output.
  *
  * If there is no translation, or the text domain isn't loaded, the original text
@@ -236,6 +275,27 @@ function esc_html__( $text, $domain = 'default' ) {
 }
 
 /**
+ * Lazily retrieve the translation of $text and escape it for safe use in HTML
+ * output.
+ *
+ * If there is no translation, or the text domain isn't loaded, the original
+ * text is escaped and returned..
+ *
+ * @since 4.9.0
+ *
+ * @param string $text   Text to translate.
+ * @param string $domain Optional. Text domain. Unique identifier for
+ *                       retrieving translated strings. Default 'default'.
+ *
+ * @return WP_String_Proxy Proxy object representing a string.
+ */
+function esc_html_l( $text, $domain = 'default' ) {
+       return new WP_Escape_HTML_Proxy(
+               new WP_Translation_Proxy( $text, $domain )
+       );
+}
+
+/**
  * Display translated text.
  *
  * @since 1.2.0
@@ -296,6 +356,28 @@ function _x( $text, $context, $domain = 'default' ) {
 }
 
 /**
+ * Lazily retrieve translated string with gettext context.
+ *
+ * Quite a few times, there will be collisions with similar translatable text
+ * found in more than two places, but with different translated context.
+ *
+ * By including the context in the pot file, translators can translate the two
+ * strings differently.
+ *
+ * @since 4.9.0
+ *
+ * @param string $text    Text to translate.
+ * @param string $context Context information for the translators.
+ * @param string $domain  Optional. Text domain. Unique identifier for
+ *                        retrieving translated strings. Default 'default'.
+ *
+ * @return WP_String_Proxy Proxy object representing a string.
+ */
+function _lx( $text, $context, $domain = 'default' ) {
+       return new WP_Contextual_Translation_Proxy( $text, $context, $domain );
+}
+
+/**
  * Display translated string with gettext context.
  *
  * @since 3.0.0
@@ -326,6 +408,25 @@ function esc_attr_x( $text, $context, $domain = 'default' ) {
 }
 
 /**
+ * Lazily translate string with gettext context, and escape it for safe use in
+ * an attribute.
+ *
+ * @since 4.9.0
+ *
+ * @param string $text    Text to translate.
+ * @param string $context Context information for the translators.
+ * @param string $domain  Optional. Text domain. Unique identifier for
+ *                        retrieving translated strings. Default 'default'.
+ *
+ * @return WP_String_Proxy Proxy object representing a string.
+ */
+function esc_attr_lx( $text, $context, $domain = 'default' ) {
+       return new WP_Escape_Attribute_Proxy(
+               new WP_Contextual_Translation_Proxy( $text, $context, $domain )
+       );
+}
+
+/**
  * Translate string with gettext context, and escapes it for safe use in HTML output.
  *
  * @since 2.9.0
@@ -341,6 +442,25 @@ function esc_html_x( $text, $context, $domain = 'default' ) {
 }
 
 /**
+ * Lazily translate string with gettext context, and escape it for safe use in
+ * HTML output.
+ *
+ * @since 4.9.0
+ *
+ * @param string $text    Text to translate.
+ * @param string $context Context information for the translators.
+ * @param string $domain  Optional. Text domain. Unique identifier for
+ *                        retrieving translated strings. Default 'default'.
+ *
+ * @return WP_String_Proxy Proxy object representing a string.
+ */
+function esc_html_lx( $text, $context, $domain = 'default' ) {
+       return new WP_Escape_HTML_Proxy(
+               new WP_Contextual_Translation_Proxy( $text, $context, $domain )
+       );
+}
+
+/**
  * Translates and retrieves the singular or plural form based on the supplied number.
  *
  * Used when you want to use the appropriate form of a string based on whether a
diff --git src/wp-includes/l10n/class-wp-contextual_translation-proxy.php src/wp-includes/l10n/class-wp-contextual_translation-proxy.php
new file mode 100644
index 0000000000..832caf4839
--- /dev/null
+++ src/wp-includes/l10n/class-wp-contextual_translation-proxy.php
@@ -0,0 +1,45 @@
+<?php
+
+/**
+ * L10n: WP_Contextual_Translation_Proxy class.
+ *
+ * @package    WordPress
+ * @subpackage L10n
+ * @since      4.9.0
+ */
+final class WP_Contextual_Translation_Proxy extends WP_String_Proxy {
+
+       private $text;
+       private $context;
+       private $domain;
+
+       /**
+        * Instantiate a WP_Translation_Proxy object.
+        *
+        * @since 4.9.0
+        *
+        * @param string $text    Text to translate.
+        * @param string $context Context of the test to translate.
+        * @param string $domain  Optional. Text domain to use for the translation.
+        */
+       public function __construct( $text, $context, $domain = 'default' ) {
+               $this->text    = $text;
+               $this->context = $context;
+               $this->domain  = $domain;
+       }
+
+       /**
+        * Get the result of evaluating the string proxy object.
+        *
+        * @since 4.9.0
+        *
+        * @return string
+        */
+       protected function get_result() {
+               return translate_with_gettext_context(
+                       $this->text,
+                       $this->context,
+                       $this->domain
+               );
+       }
+}
diff --git src/wp-includes/l10n/class-wp-escape-attribute-proxy.php src/wp-includes/l10n/class-wp-escape-attribute-proxy.php
new file mode 100644
index 0000000000..cbcea2ee0b
--- /dev/null
+++ src/wp-includes/l10n/class-wp-escape-attribute-proxy.php
@@ -0,0 +1,36 @@
+<?php
+
+/**
+ * L10n: WP_Escape_Attribute_Proxy class.
+ *
+ * @package    WordPress
+ * @subpackage L10n
+ * @since      4.9.0
+ */
+final class WP_Escape_Attribute_Proxy extends WP_String_Proxy {
+
+       private $value;
+
+       /**
+        * Instantiate a WP_Translation_Proxy object.
+        *
+        * @since 4.9.0
+        *
+        * @param mixed $value Value to be escaped. Needs to be castable to a
+        *                     string.
+        */
+       public function __construct( $value ) {
+               $this->value = $value;
+       }
+
+       /**
+        * Get the result of evaluating the string proxy object.
+        *
+        * @since 4.9.0
+        *
+        * @return string
+        */
+       protected function get_result() {
+               return esc_attr( (string) $this->value );
+       }
+}
diff --git src/wp-includes/l10n/class-wp-escape-html-proxy.php src/wp-includes/l10n/class-wp-escape-html-proxy.php
new file mode 100644
index 0000000000..97e73999f2
--- /dev/null
+++ src/wp-includes/l10n/class-wp-escape-html-proxy.php
@@ -0,0 +1,36 @@
+<?php
+
+/**
+ * L10n: WP_Escape_HTML_Proxy class.
+ *
+ * @package    WordPress
+ * @subpackage L10n
+ * @since      4.9.0
+ */
+final class WP_Escape_HTML_Proxy extends WP_String_Proxy {
+
+       private $value;
+
+       /**
+        * Instantiate a WP_Translation_Proxy object.
+        *
+        * @since 4.9.0
+        *
+        * @param mixed $value Value to be escaped. Needs to be castable to a
+        *                     string.
+        */
+       public function __construct( $value ) {
+               $this->value = $value;
+       }
+
+       /**
+        * Get the result of evaluating the string proxy object.
+        *
+        * @since 4.9.0
+        *
+        * @return string
+        */
+       protected function get_result() {
+               return esc_html( (string) $this->value );
+       }
+}
diff --git src/wp-includes/l10n/class-wp-string-proxy.php src/wp-includes/l10n/class-wp-string-proxy.php
new file mode 100644
index 0000000000..3795c0b9a7
--- /dev/null
+++ src/wp-includes/l10n/class-wp-string-proxy.php
@@ -0,0 +1,130 @@
+<?php
+
+/**
+ * L10n: WP_String_Proxy class.
+ *
+ * Implements `JsonSerializable` interface so that it gets converted to a
+ * translated string on `json_encode()`.
+ *
+ * Implements the `ArrayAccess` interface so that you can directly access
+ * individual characters in the translated string
+ *
+ * Uses magic `__get()` to make sure the result is only generated once.
+ *
+ * @package    WordPress
+ * @subpackage L10n
+ * @since      4.9.0
+ */
+abstract class WP_String_Proxy implements JsonSerializable, ArrayAccess {
+
+       /**
+        * Return the string representation of the proxy object.
+        *
+        * @since 4.9.0
+        *
+        * @return string
+        */
+       public function __toString() {
+               return $this->result;
+       }
+
+       /**
+        * Return the JSON representation of the proxy object.
+        *
+        * @since 4.9.0
+        *
+        * @return string
+        */
+       public function jsonSerialize() {
+               return $this->result;
+       }
+
+       /**
+        * Lazily evaluate the `result` property the first time it is being
+        * requested.
+        *
+        * The property is then set to the resulting value, so that the
+        * `__get()` magic method will not be called again.
+        *
+        * @since 4.9.0
+        *
+        * @param string $property Property that was requested.
+        *
+        * @return string
+        */
+       public function __get( $property ) {
+               if ( 'result' === $property ) {
+                       $this->result = $this->get_result();
+
+                       return $this->result;
+               }
+
+               $message = sprintf(
+                       'Undefined property: %s::$%s',
+                       get_class(),
+                       $property
+               );
+
+               trigger_error( $message, E_USER_NOTICE );
+
+               return null;
+       }
+
+       /**
+        * Check whether an offset into the array exists.
+        *
+        * @since 4.9.0
+        *
+        * @param mixed $offset Offset to check for.
+        *
+        * @return bool
+        */
+       public function offsetExists( $offset ) {
+               return mb_strlen( $this->result ) > $offset;
+       }
+
+       /**
+        * Retrieve a specific offset into the array.
+        *
+        * @since 4.9.0
+        *
+        * @param mixed $offset The offset to retrieve.
+        *
+        * @return mixed
+        */
+       public function offsetGet( $offset ) {
+               return $this->result[ $offset ];
+       }
+
+       /**
+        * Set a specific offset in the array.
+        *
+        * @since 4.9.0
+        *
+        * @param mixed $offset The offset to assign the value to.
+        * @param mixed $value  The value to set the offset to.
+        */
+       public function offsetSet( $offset, $value ) {
+               $this->result[ $offset ] = $value;
+       }
+
+       /**
+        * Unset a specific offset in the array.
+        *
+        * @since 4.9.0
+        *
+        * @param mixed $offset The offset to unset.
+        */
+       public function offsetUnset( $offset ) {
+               trigger_error( 'Cannot unset string offset', E_USER_ERROR );
+       }
+
+       /**
+        * Get the result of evaluating the string proxy object.
+        *
+        * @since 4.9.0
+        *
+        * @return string
+        */
+       abstract protected function get_result();
+}
diff --git src/wp-includes/l10n/class-wp-translation-proxy.php src/wp-includes/l10n/class-wp-translation-proxy.php
new file mode 100644
index 0000000000..988eec097f
--- /dev/null
+++ src/wp-includes/l10n/class-wp-translation-proxy.php
@@ -0,0 +1,38 @@
+<?php
+
+/**
+ * L10n: WP_Translation_Proxy class.
+ *
+ * @package    WordPress
+ * @subpackage L10n
+ * @since      4.9.0
+ */
+final class WP_Translation_Proxy extends WP_String_Proxy {
+
+       private $text;
+       private $domain;
+
+       /**
+        * Instantiate a WP_Translation_Proxy object.
+        *
+        * @since 4.9.0
+        *
+        * @param string $text   Text to translate.
+        * @param string $domain Optional. Text domain to use for the translation.
+        */
+       public function __construct( $text, $domain = 'default' ) {
+               $this->text   = $text;
+               $this->domain = $domain;
+       }
+
+       /**
+        * Get the result of evaluating the string proxy object.
+        *
+        * @since 4.9.0
+        *
+        * @return string
+        */
+       protected function get_result() {
+               return translate( $this->text, $this->domain );
+       }
+}
diff --git src/wp-settings.php src/wp-settings.php
index d1505c502d..748aa7a99d 100644
--- src/wp-settings.php
+++ src/wp-settings.php
@@ -239,6 +239,11 @@ require( ABSPATH . WPINC . '/rest-api/fields/class-wp-rest-comment-meta-fields.p
 require( ABSPATH . WPINC . '/rest-api/fields/class-wp-rest-post-meta-fields.php' );
 require( ABSPATH . WPINC . '/rest-api/fields/class-wp-rest-term-meta-fields.php' );
 require( ABSPATH . WPINC . '/rest-api/fields/class-wp-rest-user-meta-fields.php' );
+require( ABSPATH . WPINC . '/l10n/class-wp-string-proxy.php' );
+require( ABSPATH . WPINC . '/l10n/class-wp-translation-proxy.php' );
+require( ABSPATH . WPINC . '/l10n/class-wp-contextual_translation-proxy.php' );
+require( ABSPATH . WPINC . '/l10n/class-wp-escape-attribute-proxy.php' );
+require( ABSPATH . WPINC . '/l10n/class-wp-escape-html-proxy.php' );
 
 $GLOBALS['wp_embed'] = new WP_Embed();
 
diff --git tools/i18n/extract.php tools/i18n/extract.php
index 023b28bc69..0449cc7aca 100644
--- tools/i18n/extract.php
+++ tools/i18n/extract.php
@@ -12,6 +12,7 @@ class StringExtractor {
        var $rules = array(
                '__' => array( 'string' ),
                '_e' => array( 'string' ),
+               '_l' => array( 'string' ),
                '_n' => array( 'singular', 'plural' ),
        );
        var $comment_prefix = 'translators:';
diff --git tools/i18n/makepot.php tools/i18n/makepot.php
index 75b95e1bd2..0f4d76aca0 100644
--- tools/i18n/makepot.php
+++ tools/i18n/makepot.php
@@ -44,6 +44,7 @@ class MakePOT {
                '__' => array('string'),
                '_e' => array('string'),
                '_c' => array('string'),
+               '_l' => array('string'),
                '_n' => array('singular', 'plural'),
                '_n_noop' => array('singular', 'plural'),
                '_nc' => array('singular', 'plural'),
@@ -51,6 +52,7 @@ class MakePOT {
                '__ngettext_noop' => array('singular', 'plural'),
                '_x' => array('string', 'context'),
                '_ex' => array('string', 'context'),
+               '_lx' => array('string', 'context'),
                '_nx' => array('singular', 'plural', null, 'context'),
                '_nx_noop' => array('singular', 'plural', 'context'),
                '_n_js' => array('singular', 'plural'),
@@ -59,6 +61,8 @@ class MakePOT {
                'esc_html__' => array('string'),
                'esc_attr_e' => array('string'),
                'esc_html_e' => array('string'),
+               'esc_attr_l' => array('string'),
+               'esc_html_l' => array('string'),
                'esc_attr_x' => array('string', 'context'),
                'esc_html_x' => array('string', 'context'),
                'comments_number_link' => array('string', 'singular', 'plural'),