Merging develop to master in preparation for 2.10.0 release.

Author: weierophinney

CHANGELOG.md

@@ -2,15 +2,17 @@
 
 All notable changes to this project will be documented in this file, in reverse chronological order by release.
 
-## 2.9.3 - TBD
+## 2.10.0 - 2019-11-18
 
 ### Added
 
-- Nothing.
+- [#102](https://github.com/zendframework/zend-i18n/pull/102) adds `Zend\I18n\View\HelperTrait`, which provides annotations describing the various helpers zend-i18n provides to a zend-view renderer. The trait can be used in combination with `Zend\View\Renderer\PhpRenderer` in annotations on the `$this` variable within view scripts to provide IDE autocompletion for helper-provided methods.
 
 ### Changed
 
-- Nothing.
+- [#110](https://github.com/zendframework/zend-i18n/pull/110) modifies how `translatePlural()` works when a msgid is present, but no translations are present. It now properly returns the source-code if unable to translate the message, instead of returning an empty string (which is the behavior under `translate()` as well).
+
+- [#126](https://github.com/zendframework/zend-i18n/pull/126) modifies the package definition to put an explicit requirement on ext-intl, as it is required for the majority of functionality. Users have indicated multiple times confusion about why the component does not work after installation, when attempting to use intl functionality; requiring the extension resolves that issue.
 
 ### Deprecated
 

composer.json

@@ -17,6 +17,7 @@
     },
     "require": {
         "php": "^5.6 || ^7.0",
+        "ext-intl": "*",
         "zendframework/zend-stdlib": "^2.7 || ^3.0"
     },
     "require-dev": {
@@ -31,7 +32,6 @@
         "zendframework/zend-view": "^2.6.3"
     },
     "suggest": {
-        "ext-intl": "Required for most features of Zend\\I18n; included in default builds of PHP",
         "zendframework/zend-cache": "Zend\\Cache component",
         "zendframework/zend-config": "Zend\\Config component",
         "zendframework/zend-eventmanager": "You should install this package to use the events in the translator",
@@ -56,8 +56,8 @@
     },
     "extra": {
         "branch-alias": {
-            "dev-master": "2.9.x-dev",
-            "dev-develop": "2.10.x-dev"
+            "dev-master": "2.10.x-dev",
+            "dev-develop": "2.11.x-dev"
         },
         "zf": {
             "component": "Zend\\I18n",

composer.lock

@@ -7,6 +7,30 @@ displaying translated content.
 See the [zend-view helpers documentation](https://docs.zendframework.com/zend-view/helpers/intro/)
 for more information.
 
+> ### IDE auto-completion in templates
+>
+> The `Zend\I18n\View\HelperTrait` trait can be used to provide auto-completion
+> for modern IDEs. It defines the aliases of the view helpers in a DocBlock as
+> `@method` tags.
+>
+> #### Usage
+>
+> In order to allow auto-completion in templates, `$this` variable should be
+> type-hinted via a DocBlock at the top of your template. It is recommended that
+> you always add the `Zend\View\Renderer\PhpRenderer` as the first type, so that
+> the IDE can auto-suggest the default view helpers from `zend-view`. Next,
+> chain the `HelperTrait` from `zend-i18n` with a pipe symbol (a.k.a. vertical
+> bar) `|`:
+> ```php
+> /**
+>  * @var Zend\View\Renderer\PhpRenderer|Zend\I18n\View\HelperTrait $this
+>  */
+> ```
+>
+> You may chain as many `HelperTrait` traits as you like, depending on view
+> helpers from which Zend Framework component you are using and would like to
+> provide auto-completion for.
+
 ## CurrencyFormat Helper
 
 The `CurrencyFormat` view helper can be used to simplify rendering of localized

docs/book/view-helpers.md

@@ -387,37 +387,34 @@ public function translatePlural(
         $locale      = $locale ?: $this->getLocale();
         $translation = $this->getTranslatedMessage($singular, $locale, $textDomain);
 
-        if ($translation === null || $translation === '') {
-            if (null !== ($fallbackLocale = $this->getFallbackLocale())
-                && $locale !== $fallbackLocale
-            ) {
-                return $this->translatePlural(
-                    $singular,
-                    $plural,
-                    $number,
-                    $textDomain,
-                    $fallbackLocale
-                );
-            }
-
-            return ($number == 1 ? $singular : $plural);
-        }
-
         if (is_string($translation)) {
             $translation = [$translation];
         }
 
-        $index = $this->messages[$textDomain][$locale]
-                      ->getPluralRule()
-                      ->evaluate($number);
+        $index = ($number === 1) ? 0 : 1; // en_EN Plural rule
+        if ($this->messages[$textDomain][$locale] instanceof TextDomain) {
+            $index = $this->messages[$textDomain][$locale]
+                ->getPluralRule()
+                ->evaluate($number);
+        }
 
-        if (! isset($translation[$index])) {
-            throw new Exception\OutOfBoundsException(
-                sprintf('Provided index %d does not exist in plural array', $index)
+        if (isset($translation[$index]) && $translation[$index] !== '' && $translation[$index] !== null) {
+            return $translation[$index];
+        }
+
+        if (null !== ($fallbackLocale = $this->getFallbackLocale())
+            && $locale !== $fallbackLocale
+        ) {
+            return $this->translatePlural(
+                $singular,
+                $plural,
+                $number,
+                $textDomain,
+                $fallbackLocale
             );
         }
 
-        return $translation[$index];
+        return $index === 0 ? $singular : $plural;
     }
 
     /**

src/Translator/Translator.php

@@ -0,0 +1,37 @@
+<?php
+/**
+ * @see       https://github.com/zendframework/zend-i18n for the canonical source repository
+ * @copyright Copyright (c) 2018 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license   https://github.com/zendframework/zend-i18n/blob/master/LICENSE.md New BSD License
+ */
+
+namespace Zend\I18n\View;
+
+use IntlDateFormatter;
+
+// @codingStandardsIgnoreStart
+
+/**
+ * Helper trait for auto-completion of code in modern IDEs.
+ *
+ * The trait provides convenience methods for view helpers,
+ * defined by the zend-i18n component. It is designed to be used
+ * for type-hinting $this variable inside zend-view templates via doc blocks.
+ *
+ * The base class is PhpRenderer, followed by the helper trait from
+ * the zend-i18n component. However, multiple helper traits from different
+ * Zend Framework components can be chained afterwards.
+ *
+ * @example @var \Zend\View\Renderer\PhpRenderer|\Zend\I18n\View\HelperTrait $this
+ *
+ * @method string currencyFormat(float $number, string|null $currencyCode = null, bool|null $showDecimals = null, string|null $locale = null, string|null $pattern = null)
+ * @method string dateFormat(\DateTime|int|array $date, int $dateType = IntlDateFormatter::NONE, int $timeType = IntlDateFormatter::NONE, string|null $locale = null, string|null $pattern = null)
+ * @method string numberFormat(int|float $number, int|null $formatStyle = null, int|null $formatType = null, string|null $locale = null, int|null $decimals = null, array|null $textAttributes = null)
+ * @method string plural(array|string $strings, int $number)
+ * @method string translate(string $message, string|null $textDomain = null, string|null $locale = null)
+ * @method string translatePlural(string $singular, string $plural, int $number, string|null $textDomain = null, string|null $locale = null)
+ */
+trait HelperTrait
+{
+}
+// @codingStandardsIgnoreEnd

src/View/HelperTrait.php

@@ -255,6 +255,44 @@ public function testTranslatePlurals()
         $this->assertEquals('Message 5 (en) Plural 2', $pl2);
     }
 
+    public function testTranslatePluralsNonExistantLocale()
+    {
+        $this->translator->addTranslationFilePattern(
+            'phparray',
+            $this->testFilesDir . '/testarray',
+            'translation-%s.php'
+        );
+
+        $this->translator->setLocale('es_ES');
+
+        $pl0 = $this->translator->translatePlural('Message 5', 'Message 5 Plural', 1);
+        $pl1 = $this->translator->translatePlural('Message 5', 'Message 5 Plural', 2);
+        $pl2 = $this->translator->translatePlural('Message 5', 'Message 5 Plural', 10);
+
+        $this->assertEquals('Message 5', $pl0);
+        $this->assertEquals('Message 5 Plural', $pl1);
+        $this->assertEquals('Message 5 Plural', $pl2);
+    }
+
+    public function testTranslatePluralsNonExistantTranslation()
+    {
+        $this->translator->addTranslationFilePattern(
+            'phparray',
+            $this->testFilesDir . '/testarray',
+            'translation-%s.php'
+        );
+
+        $this->translator->setLocale('de_DE');
+
+        $pl0 = $this->translator->translatePlural('Message 12', 'Message 12 Plural', 1);
+        $pl1 = $this->translator->translatePlural('Message 12', 'Message 12 Plural', 2);
+        $pl2 = $this->translator->translatePlural('Message 12', 'Message 12 Plural', 10);
+
+        $this->assertEquals('Message 12', $pl0);
+        $this->assertEquals('Message 12 Plural', $pl1);
+        $this->assertEquals('Message 12 Plural', $pl2);
+    }
+
     public function testTranslateNoPlurals()
     {
         // Some languages such as Japanese and Chinese does not have plural forms
@@ -296,6 +334,21 @@ public function testTranslateNonExistantLocale()
         $this->assertEquals('Message 9', $this->translator->translate('Message 9'));
     }
 
+    public function testTranslateNonExistantTranslation()
+    {
+        $this->translator->addTranslationFilePattern(
+            'phparray',
+            $this->testFilesDir . '/testarray',
+            'translation-%s.php'
+        );
+
+        // Test that a locale without translations does not cause warnings
+
+        $this->translator->setLocale('de_DE');
+
+        $this->assertEquals('Message 13', $this->translator->translate('Message 13'));
+    }
+
     public function testEnableDisableEventManger()
     {
         $this->assertFalse($this->translator->isEventManagerEnabled(), 'Default value');

test/Translator/TranslatorTest.php

@@ -15,4 +15,9 @@
         'Nachricht 10 - 0',
         'Nachricht 10 - 1',
     ],
+	'Message 12' => [
+		'',
+		'',
+	],
+	'Message 13' => '',
 ];