Add section on the intl extension

Resolves #317

diff --git a/docs/migration/wsc55/php.md b/docs/migration/wsc55/php.md
index 49bedd4f90512f30a84107e58375d49a36378b29..fc3d785ed0ebf2aa21f49c9d19a00f42f0ce8ac2 100644 (file)
--- a/docs/migration/wsc55/php.md
+++ b/docs/migration/wsc55/php.md
@@ -144,6 +144,62 @@ The autogenerated name can still be requested by passing an empty string as the
 This should only be done for backwards compatibility purposes and to migrate an index with an autogenerated name to an index with an explicit name.
 An example script can be found in [WoltLab/com.woltlab.wcf.conversation@a33677ca051f](https://github.com/WoltLab/com.woltlab.wcf.conversation/commit/a33677ca051f76e1ddda1de7f8dc62a5484de16e).
 
+## Internationalization
+
+WoltLab Suite 6.0 [increases the System Requirements](#minimum-requirements) to require [PHP’s intl extension](https://www.php.net/manual/en/book.intl.php) to be installed and enabled, allowing you to rely on the functionality provided by it to better match the rules and conventions of the different languages and regions of the world.
+
+One example would be the formatting of numbers.
+WoltLab Suite included a feature to group digits within large numbers since early versions using the `StringUtil::addThousandsSeparator()` method.
+While this method was able to account for *some* language-specific differences, e.g. by selecting an appropriate separator character based on a phrase, it failed to account for all the differences in number formatting across countries and cultures.
+
+As an example, English as written in the United States of America uses commas to create groups of three digits within large numbers: 123,456,789.
+English as written in India on the other hand also uses commas, but digits are not grouped into groups of three.
+Instead the right-most three digits form a group and then another comma is added every *two* digits: 12,34,56,789.
+
+Another example would be German as used within Germany and Switzerland.
+While both countries use groups of three, the separator character differs.
+Germany uses a dot (123.456.789), whereas Switzerland uses an apostrophe (123’456’789).
+The correct choice of separator could already be configured using the afore-mentioned phrase, but this is both inconvenient and fails to account for other differences between the two countries.
+It also made it hard to keep the behavior up to date when rules change.
+
+PHP’s intl extension on the other hand builds on the official Unicode rules, by relying on the ICU library published by the Unicode consortium.
+As such it is aware of the rules of all relevant languages and regions of the world and it is already kept up to date by the operating system’s package manager.
+
+For the four example regions (en_US, en_IN, de_DE, de_CH) intl’s `NumberFormatter` class will format the number 123456789 as follows, correctly implementing the rules:
+
+```
+php > var_dump((new NumberFormatter('en_US', \NumberFormatter::DEFAULT_STYLE))->format(123_456_789));
+string(11) "123,456,789"
+php > var_dump((new NumberFormatter('en_IN', \NumberFormatter::DEFAULT_STYLE))->format(123_456_789));
+string(12) "12,34,56,789"
+php > var_dump((new NumberFormatter('de_DE', \NumberFormatter::DEFAULT_STYLE))->format(123_456_789));
+string(11) "123.456.789"
+php > var_dump((new NumberFormatter('de_CH', \NumberFormatter::DEFAULT_STYLE))->format(123_456_789));
+string(15) "123’456’789"
+```
+
+WoltLab Suite’s `StringUtil::formatNumeric()` method is updated to leverage the `NumberFormatter` internally.
+However your package might have special requirements regarding formatting, for example when formatting currencies where the position of the currency symbol differs across languages.
+In those cases your package should manually create an appropriately configured class from Intl’s feature set.
+The correct locale can be queried by the new `Language::getLocale()` method.
+
+Another use case that showcases the `Language::getLocale()` method might be localizing a country name using [`locale_get_display_region()`](https://www.php.net/manual/en/locale.getdisplayregion.php):
+
+```
+php > var_dump(\wcf\system\WCF::getLanguage()->getLocale());
+string(5) "en_US"
+php > var_dump(locale_get_display_region('_DE', \wcf\system\WCF::getLanguage()->getLocale()));
+string(7) "Germany"
+php > var_dump(locale_get_display_region('_US', \wcf\system\WCF::getLanguage()->getLocale()));
+string(13) "United States"
+php > var_dump(locale_get_display_region('_IN', \wcf\system\WCF::getLanguage()->getLocale()));
+string(5) "India"
+php > var_dump(locale_get_display_region('_BR', \wcf\system\WCF::getLanguage()->getLocale()));
+string(6) "Brazil"
+```
+
+See [WoltLab/WCF#5048](https://github.com/WoltLab/WCF/pull/5048) for details.
+
 ## Indicating parameters that hold sensitive information
 
 PHP 8.2 adds native support for redacting parameters holding sensitive information in stack traces.