diff --git a/reference/intl/transliterator/transliterate.xml b/reference/intl/transliterator/transliterate.xml
index e2cd6f3aad..24f816ca5a 100644
--- a/reference/intl/transliterator/transliterate.xml
+++ b/reference/intl/transliterator/transliterate.xml
@@ -12,34 +12,42 @@
   &reftitle.description;
   <para>&style.oop;</para>
   <methodsynopsis>
-   <modifier>public</modifier> <type>void</type><methodname>Transliterator::transliterate</methodname>
+   <modifier>public</modifier> <type>string</type><methodname>Transliterator::transliterate</methodname>
    <methodparam><type>string</type><parameter>subject</parameter></methodparam>
-   <methodparam choice="opt"><type>string</type><parameter>start</parameter></methodparam>
-   <methodparam choice="opt"><type>string</type><parameter>end</parameter></methodparam>
+   <methodparam choice="opt"><type>int</type><parameter>start</parameter></methodparam>
+   <methodparam choice="opt"><type>int</type><parameter>end</parameter></methodparam>
   </methodsynopsis>
   <para>&style.procedural;</para>
   <methodsynopsis>
    <methodname>transliterator_transliterate</methodname>
+   <methodparam><type>mixed</type><parameter>transliterator</parameter></methodparam>
    <methodparam><type>string</type><parameter>subject</parameter></methodparam>
-   <methodparam choice="opt"><type>string</type><parameter>start</parameter></methodparam>
-   <methodparam choice="opt"><type>string</type><parameter>end</parameter></methodparam>
+   <methodparam choice="opt"><type>int</type><parameter>start</parameter></methodparam>
+   <methodparam choice="opt"><type>int</type><parameter>end</parameter></methodparam>
   </methodsynopsis>
   <para>
-   Transliterates a string.
+   Transforms a string or part thereof using an ICU transliterator.
   </para>
-
-  &warn.undocumented.func;
-
  </refsect1>
 
  <refsect1 role="parameters">
   &reftitle.parameters;
   <variablelist>
+   <varlistentry>
+    <term><parameter>transliterator</parameter></term>
+    <listitem>
+     <para>
+      In the procedural version, either a <classname>Transliterator</classname>
+      or a <type>string</type> from which a
+      <classname>Transliterator</classname> can be built.
+     </para>
+    </listitem>
+   </varlistentry>
    <varlistentry>
     <term><parameter>subject</parameter></term>
     <listitem>
      <para>
-      The string to be transliterated.
+      The string to be transformed.
      </para>
     </listitem>
    </varlistentry>
@@ -47,7 +55,9 @@
     <term><parameter>start</parameter></term>
     <listitem>
      <para>
-      
+      The start index (in UTF-16 code units) from which the string will start
+      to be transformed, inclusive. Indexing starts at 0. The text before will
+      be left as is.
      </para>
     </listitem>
    </varlistentry>
@@ -55,7 +65,9 @@
     <term><parameter>end</parameter></term>
     <listitem>
      <para>
-      
+      The end index (in UTF-16 code units) until which the string will be
+      transformed, exclusive. Indexing starts at 0. The text after will be
+      left as is.
      </para>
     </listitem>
    </varlistentry>
@@ -65,8 +77,42 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   The transliterated string on success,
-   &return.falseforfailure;.
+   The transfomed string on success, &return.falseforfailure;.
+  </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title>Converting escaped UTF-16 code units</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$s = "\u304A\u65E9\u3046\u3054\u3056\u3044\u307E\u3059";
+echo transliterator_transliterate("Hex-Any/Java", $s), "\n";
+
+//now the reverse operation with a supplementary character
+$supplChar = html_entity_decode('&#x1D11E;');
+echo mb_strlen($supplChar, "UTF-8"), "\n";
+$encSupplChar = transliterator_transliterate("Any-Hex/Java", $supplChar);
+//echoes two encoded UTF-16 code units
+echo $encSupplChar, "\n";
+//and back
+echo transliterator_transliterate("Hex-Any/Java", $encSupplChar), "\n";
+]]>
+     </programlisting>
+     &example.outputs.similar;
+     <screen>
+<![CDATA[
+お早うございます
+1
+\uD834\uDD1E
+𝄞
+
+]]>
+    </screen>
+   </example>
   </para>
  </refsect1>