Improve XSLT translate description (mdn#40540)

* Improve XSLT translate description

* Apply suggestions from code review

* Update index.md

* Update files/en-us/web/xml/xpath/reference/functions/translate/index.md

---------

Co-authored-by: Hamish Willee <hamishwillee@gmail.com>

Author: Josh-Cena

files/en-us/web/xml/xpath/reference/functions/translate/index.md

@@ -28,38 +28,38 @@ The translated string.
 
 ## Description
 
-XPath notes that the translate function is not a sufficient solution for case conversion in all languages. A future version of XPath may provide additional functions for case conversion.
+For every character in `string`, if `abc` contains that character, it is replaced with the character at the same index in `XYZ`. If `abc` does not contain that character, it is kept as-is.
 
-However, this is the closest we have at present to a function that can convert a string to uppercase or lowercase.
+- If `abc` is longer than `XYZ`, then the extra characters at the end of `abc` are mapped to the empty string (i.e., they are removed from the source string).
+- If `XYZ` contains more characters than `abc`, the extra characters are ignored.
+- If a character appears multiple times in `abc`, then the first occurrence determines the replacement character.
 
-Example
+`translate()` is a character-by-character substitution function, not a regexp or string replacement function. The `abc` and `XYZ` strings represent _character ciphers_, not substrings. This means that if you run into any of the cases above, you may be using the method incorrectly (except perhaps having a longer `abc` to remove certain characters).
 
-```xml
-<xsl:value-of select="translate('The quick brown fox.', 'abcdefghijklmnopqrstuvwxyz', 'ABCDEFGHIJKLMNOPQRSTUVWXYZ')" />
+A substitution like this will not output `The quick red fox` as you might expect; instead the result is `The quick red fdx`.
+
+```xml example-bad
+<xsl:value-of select="translate('The quick brown fox', 'brown', 'red')" />
 ```
 
-Output
+## Examples
 
-```plain
-THE QUICK BROWN FOX.
-```
+### Using `translate()` for case conversion
 
-- If `abc` is longer than `XYZ`, then every occurrence of characters in `abc` that do not have a corresponding character in `XYZ` will be removed.
+XPath notes that the translate function is not a sufficient solution for case conversion in all languages. A future version of XPath may provide additional functions for case conversion.
 
-Example
+However, this is the closest we have at present to a function that can convert a string to uppercase or lowercase.
 
 ```xml
-<xsl:value-of select="translate('The quick brown fox.', 'brown', 'red')" />
+<xsl:value-of select="translate('The quick brown fox.', 'abcdefghijklmnopqrstuvwxyz', 'ABCDEFGHIJKLMNOPQRSTUVWXYZ')" />
 ```
 
 Output
 
 ```plain
-The quick red fdx.
+THE QUICK BROWN FOX.
 ```
 
-- If `XYZ` contains more characters than `abc`, the extra characters are ignored.
-
 ## Specifications
 
 [XPath 1.0 4.2](https://www.w3.org/TR/xpath-10/#function-translate)