Documentation for new translation format

docs/resources/client/i18n.md

@@ -120,6 +120,104 @@ Some places in Minecraft offer you helper methods to get a translation keys. For
 The only purpose of translation keys is for localization. Do not use them for game logic, that's what [registry names][regname] are for.
 :::
 
+### Translation Values
+
+The values given in the JSON fles are mostly passed on as they are. The only exception are parameter codes, i.e. sequences that start with a "%". These will be evaluated and replaced with the parameters that are given to the translatable Component in the code.
+
+| Value | Result |
+|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `%%` | A literal single % |
+| `%s` | A parameter from the list. The first parameter will be inserted at the first %s, the second at the second %s, and so on. |
+| `%1$s` | A parameter from the list. The number ("1" in this example) will determine which parameter to insert. This index number is 1-based, not 0-based. |
+| `%...` | Any other letter after the % is an illegal code. Some will be silently converted to `%s`, others will prevent parameter from being inserted altogeter.|
+
+Starting with NeoForge 21.0.xxx, NeoForge adds additional functionality to the parsing of values. If a translation string starts with `%n`, it will be processed as a format string using the markup language described below.
+
+#### NeoForge markup
+
+NeoForge markup will be used when a translation value starts with `%n` (which is an illegal value for vanilla values). The `%n` needs to be at the very beginning of the text, but it can be followed by one or more spaces (like in the examples below). The `%n` and the spaces after it will be stripped.
+
+##### Chat Formatting
+
+Minecraft traditionally supports 16 colors (`black`, `dark_blue`, `dark_green`, `dark_aqua`, `dark_red`, `dark_purple`, `gold`, `gray`, `dark_gray`, `blue`, `green`, `aqua`, `red`, `light_purple`, `yellow`, and `white`) and 5 formats (`obfuscated`, `bold`, `strikethrough`, `underline`, and `italic`). To format a text using those, wrap it between `<name>` and `</name>`, for example:
+
+```
+%n This <gold>golden <underline>Text</underline></gold> id <red>rad</red>!
+```
+
+There also are a couple of aliases:
+
+- `grey` and `dark_grey`
+- `b` for `bold`
+- `i` and `em` for `italic`
+- `u` and `underlined` for `underline`
+- `o` and `obf` for `obfuscated`
+- `s` and `st` for `strikethrough`
+
+Note that tags that enclose text always need to be closed and nested correctly. 
+
+##### RGB color
+
+Minecraft nowadays supports RGB colours for text. To use this, wrap the text in `<color:value>` and `</color>`, where "value" is either the decimal or hexadecimal representation of the color, for example:
+
+```
+%n <color:#BE7CDD>lilac</color> or <color:255>blue</color>?
+```
+
+##### Fonts
+
+Minecraft comes with a number of different fonts and supports adding more using resource packs. To format text using a specific font, wrap it in `<font:name>` and `</font>`, where "name" is the resource location of the font, for example:
+
+```
+%n Can you read the <font:minecraft:alt>enchantment language</font>?
+```
+
+For the fonts built into Minecraft, the "minecraft:" part is optional. For example, this produces the same result:
+
+```
+%n Can you read the <font:alt>enchantment language</font>?
+```
+
+##### Parameters
+
+Parameters are not represented using the `%s` notation, but with their index in angle brackets, for example:
+
+```
+%n Player <1> just dropped a <2>
+```
+
+These tags don't enclose text, so there's no closing tag for them.
+
+##### Plural numbers
+
+In most languages inserting numbers into text means the words around the numbers change. For example, in English it "is 1 dog" but "are 2 dogs". To enable this, add ":plural:" and an [ICU plural format string](https://unicode-org.github.io/icu-docs/apidoc/dev/icu4j/com/ibm/icu/text/PluralFormat.html) after the parameter index, for example:
+
+```
+%n There <1:plural:one{is # dog} other{are # dogs}> here.
+```
+
+English only has 2 cases, "one" for singular and "other" for plural, but there are 6 different ones, "zero", "one", "two", "few", "many" and "other". Which are supported/required depends on the language you are using.
+
+##### Reference
+
+To insert the content of another language key, use the tag `<ref:name>`, for example:
+
+```
+%n Isn't "<ref:fml.menu.accessdenied.title>" annoying?
+```
+
+##### Key Bindings
+
+To insert the current value of a keybinding, use the tag `<key:name>`, for example:
+
+```
+%n To jump, press <key:key.jump>!
+```
+
+##### Newlines
+
+When a translated string is used in a context that supports line breaks, you can insert them with `\n`. This also works in vanilla translation strings.
+
 ### Translating Mod Metadata
 
 Starting with NeoForge 20.4.179, translation files can override certain parts of [mod info][modstoml] using the following keys (where `modid` is to be replaced with the actual mod id):