[#4766] Add docblock detailing how to set include_path flag

- Added to translator loader plugin manager

library/Zend/I18n/Translator/Loader/AbstractFileLoader.php

@@ -10,22 +10,22 @@
 namespace Zend\I18n\Translator\Loader;
 
 /**
- * Abstract file loader implementation; provides facilities around resolving 
+ * Abstract file loader implementation; provides facilities around resolving
  * files via the include_path.
  */
 abstract class AbstractFileLoader implements FileLoaderInterface
 {
     /**
      * Whether or not to consult the include_path when locating files
-     * 
+     *
      * @var bool
      */
     protected $useIncludePath = false;
 
     /**
      * Indicate whether or not to use the include_path to resolve translation files
-     * 
-     * @param bool $flag 
+     *
+     * @param bool $flag
      * @return self
      */
     public function setUseIncludePath($flag = true)
@@ -35,8 +35,8 @@ public function setUseIncludePath($flag = true)
     }
 
     /**
-     * Are we using the include_path to resolve translation files? 
-     * 
+     * Are we using the include_path to resolve translation files?
+     *
      * @return bool
      */
     public function useIncludePath()
@@ -47,11 +47,11 @@ public function useIncludePath()
     /**
      * Resolve a translation file
      *
-     * Checks if the file exists and is readable, returning a boolean false if not; if the "useIncludePath" 
-     * flag is enabled, it will attempt to resolve the file from the 
+     * Checks if the file exists and is readable, returning a boolean false if not; if the "useIncludePath"
+     * flag is enabled, it will attempt to resolve the file from the
      * include_path if the file does not exist on the current working path.
-     * 
-     * @param string $filename 
+     *
+     * @param string $filename
      * @return string|false
      */
     protected function resolveFile($filename)
@@ -67,8 +67,8 @@ protected function resolveFile($filename)
 
     /**
      * Resolve a translation file via the include_path
-     * 
-     * @param string $filename 
+     *
+     * @param string $filename
      * @return string|false
      */
     protected function resolveViaIncludePath($filename)

library/Zend/I18n/Translator/LoaderPluginManager.php

@@ -18,6 +18,39 @@
  * Enforces that loaders retrieved are either instances of
  * Loader\FileLoaderInterface or Loader\RemoteLoaderInterface. Additionally,
  * it registers a number of default loaders.
+ *
+ * If you are wanting to use the ability to load translation files from the
+ * include_path, you will need to create a factory to override the defaults
+ * defined in this class. A simple factory might look like:
+ *
+ * <code>
+ * function ($translators) {
+ *     $adapter = new Gettext();
+ *     $adapter->setUseIncludePath(true);
+ *     return $adapter;
+ * }
+ * </code>
+ *
+ * You may need to override the Translator service factory to make this happen
+ * more easily. That can be done by extending it:
+ *
+ * <code>
+ * use Zend\I18n\Translator\TranslatorServiceFactory;
+ * // or Zend\Mvc\I18n\TranslatorServiceFactory
+ * use Zend\ServiceManager\ServiceLocatorInterface;
+ *
+ * class MyTranslatorServiceFactory extends TranslatorServiceFactory
+ * {
+ *     public function createService(ServiceLocatorInterface $services)
+ *     {
+ *         $translator = parent::createService($services);
+ *         $translator->getLoaderPluginManager()->setFactory(...);
+ *         return $translator;
+ *     }
+ * }
+ * </code>
+ *
+ * You would then specify your custom factory in your service configuration.
  */
 class LoaderPluginManager extends AbstractPluginManager
 {