feat(intl): add localization support

[innocenzi]

Closes #1114

This pull request's main goal is to add a new tempest/intl package with a translator and a MessageFormat 2.0 implementation (parser and formatter included).

I also moved Tempest\Support\Number, Tempest\Support\Language, and Tempest\Support\Locale to this package, because the scope makes sense.

MessageFormat

Note

I chose to go ahead with MessageFormat 2.0 instead of 1.0 (which is built in PHP's Intl extension) because this specification is more flexible and future-proof. For instance, it supports markup and custom functions.

The Tempest\Intl\MessageFormat\Formatter\MessageFormatter implementation provides a lower-level way to format MessageFormat 2.0 messages.

This would generally not be used in userland, but it's available (and used internally).

Note that the pluralization rules are generated thanks to publicly-available CLDR plural rules from the unicode project. To re-generate the class, we can just run the bin/plural-rules script.

Translator

The Tempest\Intl\Translator interface has a translate and translateForLocale method, which are both straightforward. They accept a translation key and arguments, and return the translated message (or the translation key on failure).

$translator->translate('hello', name: 'Jon Doe'); // Hello, Jon Doe!

When a translation is missing or has failed, the TranslationMiss or TranslationFailed events will be dispatched, respectively.

Messages

Messages are stored as YAML or JSON files. YAML is recommended because MF2 messages are often multiline, which is hard to work with in JSON. We could add support for PHP files as well, but the DX is better in YAML.

By default, Tempest will discover files like messages.fr.yaml, where the locale part is a valid, known locale (eg. messages.abcd.yaml will not be discovered, but locales.en_UK.yaml will).

Discovery will add the file paths to the IntlConfig, which will be used by the Tempest\Intl\Catalog implementation to load translation messages.

Configuration

From now on, the current locale is stored in Tempest\Intl\IntlConfig in the currentLocale property.

Future features that depend on the current locale should be built upon this. By default, the current locale will be Locale::default(), which uses Locale::getDefault().

[innocenzi]

Documentation PR: tempestphp/tempestphp.com#86

[aidan-casey]

Nice, PR @innocenzi! I haven't reviewed all the code, but I like the API.

Quick question, why was PHPUnit removed as a dev dependency from other sub-packages?

[innocenzi]

Quick question, why was PHPUnit removed as a dev dependency from other sub-packages?

I removed it as an attempt to fix that unknown CI error, since it was happening only for those packages. I'm not sure why none of the other packages depend on PHPUnit either

[brendt]

Great PR! I had a couple of questions, but I think this is almost ready to merge

/

[brendt]

I'm good to merge!