feature #4166 Translation custom loaders (raulfraile)

This PR was merged into the 2.3 branch.

Discussion
----------

Translation custom loaders

| Q             | A
| ------------- | ---
| Doc fix?      | no
| New docs?     | yes
| Applies to    | all
| Fixed tickets | #4156

This PR adds a documentation section for creating custom loaders and dumpers to support other formats.

Commits
-------

69491ae Improved custom formats article based on comments
c0f3b0a Fixed wrong indentation
629a008 Extra improvements based on comments
bfd78b3 Improvements based on comments
105a168 Cleanups
e2fd5fa Small fixes
dee7fb2 Link from introduction section
8b6c584 Added custom format page to translation component

components/map.rst.inc

@@ -130,6 +130,7 @@
 
   * :doc:`/components/translation/introduction`
   * :doc:`/components/translation/usage`
+  * :doc:`/components/translation/custom_formats`
 
 * :doc:`/components/yaml/index`
 

components/translation/custom_formats.rst

@@ -0,0 +1,114 @@
+.. index::
+    single: Translation; Adding Custom Format Support
+
+Adding Custom Format Support
+============================
+
+Sometimes, you need to deal with custom formats for translation files. The
+Translation component is flexible enough to support this. Just create a
+loader (to load translations) and, optionally, a dumper (to dump translations).
+
+Imagine that you have a custom format where translation messages are defined
+using one line for each translation and parentheses to wrap the key and the
+message. A translation file would look like this:
+
+.. code-block:: text
+
+    (welcome)(accueil)
+    (goodbye)(au revoir)
+    (hello)(bonjour)
+
+Creating a Custom Loader
+------------------------
+
+To define a custom loader that is able to read this kind of files, you must create a
+new class that implements the
+:class:`Symfony\\Component\\Translation\\Loader\\LoaderInterface`. The
+:method:`Symfony\\Component\\Translation\\Loader\\LoaderInterface::load`
+method will get a filename and parse it into an array. Then, it will
+create the catalog that will be returned::
+
+    use Symfony\Component\Translation\MessageCatalogue;
+    use Symfony\Component\Translation\Loader\LoaderInterface;
+
+    class MyFormatLoader implements LoaderInterface
+    {
+        public function load($resource, $locale, $domain = 'messages')
+        {
+            $messages = array();
+            $lines = file($resource);
+
+            foreach ($lines as $line) {
+                if (preg_match('/\(([^\)]+)\)\(([^\)]+)\)/', $line, $matches)) {
+                    $messages[$matches[1]] = $matches[2];
+                }
+            }
+
+            $catalogue = new MessageCatalogue($locale);
+            $catalogue->add($messages, $domain);
+
+            return $catalogue;
+        }
+
+    }
+
+Once created, it can be used as any other loader::
+
+    use Symfony\Component\Translation\Translator;
+
+    $translator = new Translator('fr_FR');
+    $translator->addLoader('my_format', new MyFormatLoader());
+
+    $translator->addResource('my_format', __DIR__.'/translations/messages.txt', 'fr_FR');
+
+    echo $translator->trans('welcome');
+
+It will print *"accueil"*.
+
+Creating a Custom Dumper
+------------------------
+
+It is also possible to create a custom dumper for your format, which is
+useful when using the extraction commands. To do so, a new class
+implementing the
+:class:`Symfony\\Component\\Translation\\Dumper\\DumperInterface`
+must be created. To write the dump contents into a file, extending the
+:class:`Symfony\\Component\\Translation\\Dumper\\FileDumper` class
+will save a few lines::
+
+    use Symfony\Component\Translation\MessageCatalogue;
+    use Symfony\Component\Translation\Dumper\FileDumper;
+
+    class MyFormatDumper extends FileDumper
+    {
+        protected function format(MessageCatalogue $messages, $domain = 'messages')
+        {
+            $output = '';
+
+            foreach ($messages->all($domain) as $source => $target) {
+                $output .= sprintf("(%s)(%s)\n", $source, $target);
+            }
+
+            return $output;
+        }
+
+        protected function getExtension()
+        {
+            return 'txt';
+        }
+    }
+
+The :method:`Symfony\\Component\\Translation\\Dumper\\FileDumper::format`
+method creates the output string, that will be used by the
+:method:`Symfony\\Component\\Translation\\Dumper\\FileDumper::dump` method
+of the FileDumper class to create the file. The dumper can be used like any other
+built-in dumper. In the following example, the translation messages defined in the
+YAML file are dumped into a text file with the custom format::
+
+    use Symfony\Component\Translation\Loader\YamlFileLoader;
+
+    $loader = new YamlFileLoader();
+    $catalogue = $loader->load(__DIR__ . '/translations/messages.fr_FR.yml' , 'fr_FR');
+
+    $dumper = new MyFormatDumper();
+    $dumper->dump($catalogue, array('path' => __DIR__.'/dumps'));

components/translation/index.rst

@@ -6,3 +6,4 @@ Translation
 
     introduction
     usage
+    custom_formats

components/translation/introduction.rst

@@ -62,8 +62,7 @@ The Translation component uses Loader classes to load catalogs. You can load
 multiple resources for the same locale, which will then be combined into one
 catalog.
 
-The component comes with some default Loaders and you can create your own
-Loader too. The default loaders are:
+The component comes with some default loaders:
 
 * :class:`Symfony\\Component\\Translation\\Loader\\ArrayLoader` - to load
   catalogs from PHP arrays.
@@ -95,6 +94,9 @@ Loader too. The default loaders are:
 
 All file loaders require the :doc:`Config component </components/config/index>`.
 
+You can also :doc:`create your own Loader </components/translation/custom_formats>`,
+in case the format is not already supported by one of the default loaders.
+
 At first, you should add one or more loaders to the ``Translator``::
 
     // ...