Feature rewrite

.gitignore

@@ -4,3 +4,4 @@ composer.lock
 *.komodoproject
 .php_cs.cache
 _meta
+.serenata

CHANGELOG.md

@@ -4,6 +4,27 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## [4.4.0]
+Complete rewrite of the Translator.
+
+Instead of `LocalePathBuilder -> MessageTranslator`, the new translator introduce the concept of `Locale`, `Dictionary` and `Translator`. So now you create a locale, which enables you to create a dictionary for that locale, which finally allows you to create a translator which will used that dictionary.
+
+Instead of loading multiple locale on top of each other, a locale can depend on other locale using the configuration file (ie. `locale.yaml`). See the updated doc for more information.
+
+Plural rule are now defined in the locale configuration file instead of the special `@PLURAL_RULE` key.
+
+All methods of the `Translator` are the same for backward compatibility. The only change is the constructor, which now requires a `DictionaryInterface` instance.
+
+**Detailed changes** :
+- `MessageTranslator` is now `Translator`.
+- `Translator` requires a `DictionaryInterface` as some constructor argument instead of paths.
+- `LocalePathBuilder` removed.
+- `DictionaryInterface` now extends `UserFrosting\Support\Repository\Repository` instead of the `Translator`. The raw data can be accessed using the Dictionary methods.
+- `@PLURAL_RULE` special key removed. Use the Locale configuration file (`locale.yaml`) `plural_rule` attribute instead.
+- Translator can't load multiple locale anymore. Use the Locale configuration file `parents` attribute instead.
+
+See updated [documentation](README.md) for more details on how to use the new Translator, Locale and Dictionary. 
+
 ## [4.3.0]
 - Dropping support for PHP 5.6 & 7.0
 - Updated Twig to 2.x
@@ -36,6 +57,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) a
 ## 4.0.0
 - Initial release
 
+[4.4.0]: https://github.com/userfrosting/i18n/compare/4.3.0...4.4.0
 [4.3.0]: https://github.com/userfrosting/i18n/compare/4.2.1...4.3.0
 [4.2.1]: https://github.com/userfrosting/i18n/compare/4.2.0...4.2.1
 [4.2.0]: https://github.com/userfrosting/i18n/compare/4.1.0...4.2.0

composer.json

@@ -18,11 +18,13 @@
     "require": {
         "php": ">=7.1",
         "twig/twig": "^2.11",
-        "userfrosting/support": "~4.3.0"
+        "userfrosting/support": "~4.3.1"
     },
 	"require-dev": {
         "friendsofphp/php-cs-fixer": "^2.13",
-        "phpunit/phpunit": "^7.5"
+        "mockery/mockery": "^1.2",
+        "phpunit/phpunit": "^7.5",
+        "victorjonsson/markdowndocs": "^1.3"
     },
     "autoload": {
         "psr-4": {

docs/README.md

@@ -0,0 +1,5 @@
+# Building doc
+
+```
+vendor/bin/phpdoc-md generate src/ > docs/api.md
+```

src/Dictionary.php

@@ -0,0 +1,177 @@
+<?php
+
+/*
+ * UserFrosting i18n (http://www.userfrosting.com)
+ *
+ * @link      https://github.com/userfrosting/i18n
+ * @copyright Copyright (c) 2013-2019 Alexander Weissman, Louis Charette
+ * @license   https://github.com/userfrosting/i18n/blob/master/LICENSE.md (MIT License)
+ */
+
+namespace UserFrosting\I18n;
+
+use UserFrosting\Support\Repository\Loader\ArrayFileLoader;
+use UserFrosting\Support\Repository\Loader\FileRepositoryLoader;
+use UserFrosting\Support\Repository\Repository;
+use UserFrosting\UniformResourceLocator\ResourceLocatorInterface;
+
+/**
+ * Locale Dictionary.
+ *
+ * Load all locale all "Key => translation" data matrix
+ *
+ * @author Louis Charette
+ */
+class Dictionary extends Repository implements DictionaryInterface
+{
+    /**
+     * @var string Base URI for locator
+     */
+    protected $uri = 'locale://';
+
+    /**
+     * @var LocaleInterface
+     */
+    protected $locale;
+
+    /**
+     * @var ResourceLocatorInterface
+     */
+    protected $locator;
+
+    /**
+     * @var FileRepositoryLoader
+     */
+    protected $fileLoader;
+
+    /**
+     * @var array Locale "Key => translation" data matrix cache
+     */
+    protected $items = [];
+
+    /**
+     * @param LocaleInterface          $locale
+     * @param ResourceLocatorInterface $locator
+     * @param FileRepositoryLoader     $fileLoader File loader used to load each dictionnay files (default to Array Loader)
+     */
+    public function __construct(LocaleInterface $locale, ResourceLocatorInterface $locator, FileRepositoryLoader $fileLoader = null)
+    {
+        $this->locale = $locale;
+        $this->locator = $locator;
+        $this->fileLoader = is_null($fileLoader) ? new ArrayFileLoader([]) : $fileLoader;
+    }
+
+    /**
+     * Returns all loaded locale Key => Translation data dictionary.
+     * Won't load the whole thing twice if already loaded in the class.
+     *
+     * @return string[] The locale dictionary
+     */
+    public function getDictionary(): array
+    {
+        if (empty($this->items)) {
+            $this->items = $this->loadDictionary();
+        }
+
+        return $this->items;
+    }
+
+    /**
+     * Set the locator base URI (default 'locale://').
+     *
+     * @param string $uri
+     */
+    public function setUri(string $uri): void
+    {
+        $this->uri = $uri;
+    }
+
+    /**
+     * Return the associate locale.
+     *
+     * @return LocaleInterface
+     */
+    public function getLocale(): LocaleInterface
+    {
+        return $this->locale;
+    }
+
+    /**
+     * Return the file repository loader used to load.
+     *
+     * @return FileRepositoryLoader
+     */
+    public function getFileLoader(): FileRepositoryLoader
+    {
+        return $this->fileLoader;
+    }
+
+    /**
+     * Load the dictionary from file.
+     *
+     * @return (string|array)[] The locale dictionary
+     */
+    protected function loadDictionary(): array
+    {
+        $dictionary = [];
+
+        // List of loaded locales
+        $loadedLocale = [$this->locale->getIndentifier()];
+
+        // Get list of files to load
+        $files = $this->getFiles();
+        $files = $this->filterDictionaryFiles($files);
+
+        // Load all files content if files are present
+        if (!empty($files)) {
+            $loader = $this->getFileLoader();
+            $loader->setPaths($files);
+
+            $dictionary = $loader->load();
+        }
+
+        // Now load dependent dictionnaries
+        foreach ($this->locale->getDependentLocales() as $locale) {
+
+            // Stop if locale already loaded to prevent recursion
+            $localesToLoad = array_merge([$locale->getIndentifier()], $locale->getDependentLocalesIdentifier());
+            $intersection = array_intersect($localesToLoad, $loadedLocale);
+            if (!empty($intersection)) {
+                throw new \LogicException("Can't load dictionary. Dependencies recursion detected : ".implode(', ', $intersection));
+            }
+
+            $dependentDictionary = new self($locale, $this->locator, $this->fileLoader);
+            $dictionary = array_replace_recursive($dependentDictionary->getDictionary(), $dictionary);
+
+            $loadedLocale[] = $locale->getIndentifier();
+        }
+
+        return $dictionary;
+    }
+
+    /**
+     * Remove config files from locator results and convert ResourceInterface to path/string.
+     *
+     * @param \UserFrosting\UniformResourceLocator\ResourceInterface[] $files
+     *
+     * @return string[]
+     */
+    protected function filterDictionaryFiles(array $files): array
+    {
+        return array_filter($files, function ($file) {
+            if ($file->getExtension() == 'php') {
+                return (string) $file;
+            }
+        });
+    }
+
+    /**
+     * List all files for a given locale using the locator.
+     *
+     * @return \UserFrosting\UniformResourceLocator\ResourceInterface[]
+     */
+    protected function getFiles(): array
+    {
+        return $this->locator->listResources($this->uri.$this->locale->getIndentifier(), true);
+    }
+}

src/DictionaryInterface.php

@@ -0,0 +1,39 @@
+<?php
+
+/*
+ * UserFrosting i18n (http://www.userfrosting.com)
+ *
+ * @link      https://github.com/userfrosting/i18n
+ * @copyright Copyright (c) 2013-2019 Alexander Weissman, Louis Charette
+ * @license   https://github.com/userfrosting/i18n/blob/master/LICENSE.md (MIT License)
+ */
+
+namespace UserFrosting\I18n;
+
+use Illuminate\Contracts\Config\Repository;
+
+/**
+ * Locale Dictionary.
+ *
+ * Used to return all "Key => translation" data matrix
+ * Extend the Config repository to have acess to all the standard `has`, `get`,
+ * etc. public methods on the dictionnay array
+ *
+ * @author Louis Charette
+ */
+interface DictionaryInterface extends Repository
+{
+    /**
+     * Returns all loaded locale Key => Translation data dictionary.
+     *
+     * @return string[] The locale dictionary
+     */
+    public function getDictionary(): array;
+
+    /**
+     * Return the associate locale.
+     *
+     * @return LocaleInterface
+     */
+    public function getLocale(): LocaleInterface;
+}