feat: config, catalog and translator

Author: innocenzi

composer.json

@@ -139,6 +139,7 @@
             "packages/datetime/src/functions.php",
             "packages/debug/src/functions.php",
             "packages/event-bus/src/functions.php",
+            "packages/i18n/src/functions.php",
             "packages/mapper/src/functions.php",
             "packages/reflection/src/functions.php",
             "packages/router/src/functions.php",
@@ -205,7 +206,7 @@
         "phpstan": "vendor/bin/phpstan analyse src tests --memory-limit=1G",
         "rector": "vendor/bin/rector process --no-ansi",
         "merge": "php -d\"error_reporting = E_ALL & ~E_DEPRECATED\" vendor/bin/monorepo-builder merge",
-				"i18n:plural": "./packages/i18n/bin/plural-rules.php",
+        "i18n:plural": "./packages/i18n/bin/plural-rules.php",
         "release": [
             "composer qa",
             "./bin/release"

packages/i18n/composer.json

@@ -5,12 +5,17 @@
     "minimum-stability": "dev",
     "require": {
         "php": "^8.4",
-        "tempest/container": "dev-main"
+        "tempest/core": "dev-main",
+        "tempest/container": "dev-main",
+        "tempest/datetime": "dev-main"
     },
     "require-dev": {
         "phpunit/phpunit": "^11.5.17"
     },
     "autoload": {
+        "files": [
+            "src/functions.php"
+        ],
         "psr-4": {
             "Tempest\\Internationalization\\": "src"
         }

packages/i18n/src/Catalog/Catalog.php

@@ -0,0 +1,23 @@
+<?php
+
+namespace Tempest\Internationalization\Catalog;
+
+use Tempest\Support\Language\Locale;
+
+interface Catalog
+{
+    /**
+     * Determines if a translation exists for a given key in the specified locale.
+     */
+    public function has(Locale $locale, string $key): bool;
+
+    /**
+     * Gets the translation for a given key in the specified locale.
+     */
+    public function get(Locale $locale, string $key): ?string;
+
+    /**
+     * Adds a translation message for a given key in the specified locale.
+     */
+    public function add(Locale $locale, string $key, string $message): self;
+}

packages/i18n/src/Catalog/CatalogInitializer.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace Tempest\Internationalization\Catalog;
+
+use Tempest\Container\Container;
+use Tempest\Container\Initializer;
+use Tempest\Internationalization\InternationalizationConfig;
+use Tempest\Support\Arr;
+use Tempest\Support\Filesystem;
+use Tempest\Support\Json;
+use Tempest\Support\Language\Locale;
+
+final class CatalogInitializer implements Initializer
+{
+    public function initialize(Container $container): Catalog
+    {
+        $config = $container->get(InternationalizationConfig::class);
+        $catalog = [];
+
+        foreach ($config->translationMessagePaths as $locale => $paths) {
+            $locale = Locale::from($locale)->value;
+            $catalog[$locale] ??= [];
+
+            foreach ($paths as $path) {
+                $messages = Json\decode(Filesystem\read_file($path));
+                $messages = Arr\undot($messages);
+
+                foreach ($messages as $key => $message) {
+                    $catalog[$locale][$key] = $message;
+                }
+            }
+        }
+
+        return new GenericCatalog($catalog);
+    }
+}

packages/i18n/src/Catalog/GenericCatalog.php

@@ -0,0 +1,41 @@
+<?php
+
+namespace Tempest\Internationalization\Catalog;
+
+use Tempest\Internationalization\InternationalizationConfig;
+use Tempest\Support\Arr;
+use Tempest\Support\Language\Locale;
+
+final class GenericCatalog implements Catalog
+{
+    /**
+     * @var array<string,string[]> $catalog
+     */
+    public function __construct(
+        private array $catalog = [],
+    ) {}
+
+    public function has(Locale $locale, string $key): bool
+    {
+        return Arr\has($this->catalog, "{$locale->value}.{$key}");
+    }
+
+    public function get(Locale $locale, string $key): ?string
+    {
+        return Arr\get_by_key(
+            array: $this->catalog,
+            key: "{$locale->value}.{$key}",
+            default: Arr\get_by_key(
+                array: $this->catalog,
+                key: "{$locale->getLanguage()}.{$key}",
+            ),
+        );
+    }
+
+    public function add(Locale $locale, string $key, string $message): self
+    {
+        $this->catalog = Arr\set_by_key($this->catalog, "{$locale->value}.{$key}", $message);
+
+        return $this;
+    }
+}

packages/i18n/src/InternationalizationConfig.php

@@ -2,10 +2,40 @@
 
 namespace Tempest\Internationalization;
 
+use Tempest\Internationalization\MessageFormat\Formatter\MessageFormatFunction;
+use Tempest\Support\Language\Locale;
+
 final class InternationalizationConfig
 {
+    /** @var MessageFormatFunction[] */
+    public array $functions = [];
+
+    /** @var array<string,string[]> */
+    public array $translationMessagePaths = [];
+
     public function __construct(
-        /** @var MessageFormatFunction[] */
-        public array $functions = [],
+        /**
+         * Defines the locale used throughout the application.
+         */
+        public Locale $currentLocale,
+
+        /**
+         * Defines the fallback locale used when a translation message does not exist in the current locale.
+         */
+        public Locale $fallbackLocale,
     ) {}
+
+    public function addMessageFormatFunction(MessageFormatFunction $fn): void
+    {
+        $this->functions[] = $fn;
+    }
+
+    public function addTranslationMessageFile(Locale $locale, string $path): void
+    {
+        $this->translationMessagePaths[$locale->value] ??= [];
+
+        if (! in_array($path, $this->translationMessagePaths[$locale->value], strict: true)) {
+            $this->translationMessagePaths[$locale->value][] = $path;
+        }
+    }
 }

packages/i18n/src/MessageFormatFunctionDiscovery.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Internationalization;
+
+use Tempest\Container\Container;
+use Tempest\Discovery\Discovery;
+use Tempest\Discovery\DiscoveryLocation;
+use Tempest\Discovery\IsDiscovery;
+use Tempest\Internationalization\MessageFormat\Formatter\MessageFormatFunction;
+use Tempest\Reflection\ClassReflector;
+
+final class MessageFormatFunctionDiscovery implements Discovery
+{
+    use IsDiscovery;
+
+    public function __construct(
+        private readonly Container $container,
+        private readonly InternationalizationConfig $config,
+    ) {}
+
+    public function discover(DiscoveryLocation $location, ClassReflector $class): void
+    {
+        if (! $class->implements(MessageFormatFunction::class)) {
+            return;
+        }
+
+        $this->discoveryItems->add($location, $class->getName());
+    }
+
+    public function apply(): void
+    {
+        foreach ($this->discoveryItems as $className) {
+            $this->config->addMessageFormatFunction($this->container->get($className));
+        }
+    }
+}

packages/i18n/src/MessageFormatterInitializer.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace Tempest\Internationalization;
+
+use Tempest\Container\Container;
+use Tempest\Container\Initializer;
+use Tempest\Internationalization\MessageFormat\Formatter\MessageFormatter;
+use Tempest\Internationalization\PluralRules\PluralRulesMatcher;
+
+final class MessageFormatterInitializer implements Initializer
+{
+    public function initialize(Container $container): mixed
+    {
+        $config = $container->get(InternationalizationConfig::class);
+
+        return new MessageFormatter(
+            functions: $config->functions,
+            pluralRules: new PluralRulesMatcher(),
+        );
+    }
+}

packages/i18n/src/TranslationMessageDiscovery.php

@@ -0,0 +1,68 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Internationalization;
+
+use Tempest\Discovery\DiscoversPath;
+use Tempest\Discovery\Discovery;
+use Tempest\Discovery\DiscoveryLocation;
+use Tempest\Discovery\IsDiscovery;
+use Tempest\Reflection\ClassReflector;
+use Tempest\Support\Language\Locale;
+
+use function Tempest\Support\arr;
+use function Tempest\Support\str;
+use function Tempest\Support\Str\ends_with;
+
+final class TranslationMessageDiscovery implements Discovery, DiscoversPath
+{
+    use IsDiscovery;
+
+    public function __construct(
+        private readonly InternationalizationConfig $config,
+    ) {}
+
+    public function discover(DiscoveryLocation $location, ClassReflector $class): void
+    {
+        return;
+    }
+
+    public function discoverPath(DiscoveryLocation $location, string $path): void
+    {
+        if (! ends_with($path, '.json')) {
+            return;
+        }
+
+        if (! $this->isLocale($locale = str($path)->beforeLast('.')->afterLast('.')->toString())) {
+            return;
+        }
+
+        if (! is_file($path)) {
+            return;
+        }
+
+        $this->discoveryItems->add($location, [$path, $locale]);
+    }
+
+    public function apply(): void
+    {
+        foreach ($this->discoveryItems as [$path, $locale]) {
+            $this->config->addTranslationMessageFile(Locale::from($locale), $path);
+        }
+    }
+
+    private function isLocale(string $candidate): bool
+    {
+        $locale = arr(Locale::cases())
+            ->first(function (Locale $locale) use ($candidate) {
+                if (strtolower($locale->value) === strtolower($candidate)) {
+                    return true;
+                }
+
+                return strtolower($locale->getLanguage()) === strtolower($candidate);
+            });
+
+        return ! is_null($locale);
+    }
+}

packages/i18n/src/Translator/GenericTranslator.php

@@ -0,0 +1,55 @@
+<?php
+
+namespace Tempest\Internationalization\Translator;
+
+use Tempest\Core\ExceptionReporter;
+use Tempest\EventBus\EventBus;
+use Tempest\Internationalization\Catalog\Catalog;
+use Tempest\Internationalization\InternationalizationConfig;
+use Tempest\Internationalization\MessageFormat\Formatter\MessageFormatter;
+use Tempest\Support\Language\Locale;
+
+final class GenericTranslator implements Translator
+{
+    public function __construct(
+        private readonly InternationalizationConfig $config,
+        private readonly Catalog $catalog,
+        private readonly MessageFormatter $formatter,
+        private readonly ?EventBus $eventBus = null,
+    ) {}
+
+    public function translateForLocale(Locale $locale, string $key, mixed ...$arguments): string
+    {
+        $message = $this->catalog->get($locale, $key);
+
+        if (! $message) {
+            $message = $this->catalog->get($this->config->fallbackLocale, $key);
+        }
+
+        if (! $message) {
+            $this->eventBus?->dispatch(new TranslationMiss(
+                locale: $locale,
+                key: $key,
+            ));
+
+            return $key;
+        }
+
+        try {
+            return $this->formatter->format($message, ...$arguments);
+        } catch (\Throwable $exception) {
+            $this->eventBus?->dispatch(new TranslationFailure(
+                locale: $locale,
+                key: $key,
+                exception: $exception,
+            ));
+
+            return $key;
+        }
+    }
+
+    public function translate(string $key, mixed ...$arguments): string
+    {
+        return $this->translateForLocale($this->config->currentLocale, $key, ...$arguments);
+    }
+}