From 8b6c584cf56d15762355f4c53ef8658a42021d44 Mon Sep 17 00:00:00 2001 From: Raul Fraile Date: Fri, 22 Aug 2014 21:11:18 +0200 Subject: [PATCH 1/8] Added custom format page to translation component --- components/translation/custom_formats.rst | 112 ++++++++++++++++++++++ components/translation/index.rst | 1 + 2 files changed, 113 insertions(+) create mode 100644 components/translation/custom_formats.rst diff --git a/components/translation/custom_formats.rst b/components/translation/custom_formats.rst new file mode 100644 index 00000000000..c7fda423d85 --- /dev/null +++ b/components/translation/custom_formats.rst @@ -0,0 +1,112 @@ +.. index:: + single: Translation; Custom formats + +Custom formats +============== + +Sometimes, you need to deal with custom formats for translation files. The +Translation component is flexible enough to support this, just creating a +loader (to load translations) and, optionally, a dumper (to dump translations). + +Let's imagine you have a custom format where translation messages are defined +using one line for each translation and parenthesis to wrap the key and the +message. A translation file would look like this: + + (welcome)(Bienvenido) + (goodbye)(Adios) + (hello)(Hola) + +To define a custom loader able to read this kind of files, you must create a +new class that implements the +:class:`Symfony\\Component\\Translation\\Loader\\LoaderInterface` interface, +which defines a +:method:`Symfony\\Component\\Translation\\Loader\\LoaderInterface::load` +method. In the loader, this method will get a filename and parse it to create 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:: + + $translator = new Translator('es_ES'); + $translator->addLoader('my_format', new MyFormatLoader()); + + $translator->addResource('my_format', __DIR__.'/translations/messages.txt', 'es_ES'); + + echo $translator->trans('welcome'); + +It will print *"Bienvenido"*. + +It is also possible to create a custom dumper for your format. To do so, +a new class implementing the +DumperInterface +:class:`Symfony\\Component\\Translation\\Dumper\\DumperInterface` +interface 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 + { + + public 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 :class:`Symfony\\Component\\Translation\\Dumper\\FileDumper` class to +create the file. The dumper can be used like any other +built-in dumper. In this 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; + use RaulFraile\Dumper\CustomDumper; + + include_once __DIR__. '/vendor/autoload.php'; + + $loader = new YamlFileLoader(); + $catalogue = $loader->load(__DIR__ . '/translations/messages.es_ES.yml' , 'es_ES'); + + $dumper = new CustomDumper(); + $dumper->dump($catalogue, array('path' => __DIR__.'/dumps')); diff --git a/components/translation/index.rst b/components/translation/index.rst index 3f87cbc1425..c50e43f2be7 100644 --- a/components/translation/index.rst +++ b/components/translation/index.rst @@ -6,3 +6,4 @@ Translation introduction usage + custom_formats From dee7fb272cd33ebd5f265a15d996642d5e0cd3d4 Mon Sep 17 00:00:00 2001 From: Raul Fraile Date: Fri, 22 Aug 2014 21:13:56 +0200 Subject: [PATCH 2/8] Link from introduction section --- components/translation/introduction.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/components/translation/introduction.rst b/components/translation/introduction.rst index 7300f01f7a9..e13c1a13923 100644 --- a/components/translation/introduction.rst +++ b/components/translation/introduction.rst @@ -62,8 +62,9 @@ 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 and you can +:doc:`create your own Loader too`. The +default loaders are: * :class:`Symfony\\Component\\Translation\\Loader\\ArrayLoader` - to load catalogs from PHP arrays. From e2fd5fa0be5a065536290a756482953bed998209 Mon Sep 17 00:00:00 2001 From: Raul Fraile Date: Fri, 22 Aug 2014 21:17:39 +0200 Subject: [PATCH 3/8] Small fixes --- components/translation/custom_formats.rst | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/components/translation/custom_formats.rst b/components/translation/custom_formats.rst index c7fda423d85..28e03c13ede 100644 --- a/components/translation/custom_formats.rst +++ b/components/translation/custom_formats.rst @@ -10,7 +10,7 @@ loader (to load translations) and, optionally, a dumper (to dump translations). Let's imagine you have a custom format where translation messages are defined using one line for each translation and parenthesis to wrap the key and the -message. A translation file would look like this: +message. A translation file would look like this:: (welcome)(Bienvenido) (goodbye)(Adios) @@ -22,14 +22,13 @@ new class that implements the which defines a :method:`Symfony\\Component\\Translation\\Loader\\LoaderInterface::load` method. In the loader, this method will get a filename and parse it to create an -array. Then, it will create the catalog that will be returned. +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(); @@ -62,12 +61,11 @@ It will print *"Bienvenido"*. It is also possible to create a custom dumper for your format. To do so, a new class implementing the -DumperInterface :class:`Symfony\\Component\\Translation\\Dumper\\DumperInterface` interface 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. +will save a few lines:: use Symfony\Component\Translation\MessageCatalogue; use Symfony\Component\Translation\Dumper\FileDumper; From 105a168ffa9147c745c60a84b8d075ecf9534e2a Mon Sep 17 00:00:00 2001 From: Raul Fraile Date: Fri, 22 Aug 2014 21:23:50 +0200 Subject: [PATCH 4/8] Cleanups --- components/translation/custom_formats.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/components/translation/custom_formats.rst b/components/translation/custom_formats.rst index 28e03c13ede..8a1520e3a1e 100644 --- a/components/translation/custom_formats.rst +++ b/components/translation/custom_formats.rst @@ -99,12 +99,11 @@ built-in dumper. In this example, the translation messages defined in the YAML f are dumped into a text file with the custom format:: use Symfony\Component\Translation\Loader\YamlFileLoader; - use RaulFraile\Dumper\CustomDumper; include_once __DIR__. '/vendor/autoload.php'; $loader = new YamlFileLoader(); $catalogue = $loader->load(__DIR__ . '/translations/messages.es_ES.yml' , 'es_ES'); - $dumper = new CustomDumper(); + $dumper = new MyFormatDumper(); $dumper->dump($catalogue, array('path' => __DIR__.'/dumps')); From bfd78b33d71a7de45e69368e75662ac94c6b4876 Mon Sep 17 00:00:00 2001 From: Raul Fraile Date: Sat, 23 Aug 2014 22:15:35 +0200 Subject: [PATCH 5/8] Improvements based on comments --- components/map.rst.inc | 1 + components/translation/custom_formats.rst | 23 +++++++++++++++-------- components/translation/introduction.rst | 4 ++-- 3 files changed, 18 insertions(+), 10 deletions(-) diff --git a/components/map.rst.inc b/components/map.rst.inc index 81d63df5562..572f19352d8 100644 --- a/components/map.rst.inc +++ b/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` diff --git a/components/translation/custom_formats.rst b/components/translation/custom_formats.rst index 8a1520e3a1e..18ce1353e39 100644 --- a/components/translation/custom_formats.rst +++ b/components/translation/custom_formats.rst @@ -1,7 +1,7 @@ .. index:: single: Translation; Custom formats -Custom formats +Custom Formats ============== Sometimes, you need to deal with custom formats for translation files. The @@ -10,19 +10,23 @@ loader (to load translations) and, optionally, a dumper (to dump translations). Let's imagine you have a custom format where translation messages are defined using one line for each translation and parenthesis to wrap the key and the -message. A translation file would look like this:: +message. A translation file would look like this: + +.. code-block:: text (welcome)(Bienvenido) (goodbye)(Adios) (hello)(Hola) +Custom Loader +------------- + To define a custom loader able to read this kind of files, you must create a new class that implements the -:class:`Symfony\\Component\\Translation\\Loader\\LoaderInterface` interface, -which defines a +:class:`Symfony\\Component\\Translation\\Loader\\LoaderInterface`. The :method:`Symfony\\Component\\Translation\\Loader\\LoaderInterface::load` -method. In the loader, this method will get a filename and parse it to create an -array. Then, it will create the catalog that will be returned:: +method will get a filename and parse it into an array. Then, it will +create the catalogue that will be returned:: use Symfony\Component\Translation\MessageCatalogue; use Symfony\Component\Translation\Loader\LoaderInterface; @@ -59,8 +63,11 @@ Once created, it can be used as any other loader:: It will print *"Bienvenido"*. -It is also possible to create a custom dumper for your format. To do so, -a new class implementing the +Custom Dumper +------------- + +It is also possible to create a custom dumper for your format, useful when using +the extraction commands. To do so, a new class implementing the :class:`Symfony\\Component\\Translation\\Dumper\\DumperInterface` interface must be created. To write the dump contents into a file, extending the diff --git a/components/translation/introduction.rst b/components/translation/introduction.rst index e13c1a13923..2d631853fe0 100644 --- a/components/translation/introduction.rst +++ b/components/translation/introduction.rst @@ -62,8 +62,8 @@ 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 -:doc:`create your own Loader too`. The +The component comes with some default loaders and you can +:doc:`create your own Loader too `. The default loaders are: * :class:`Symfony\\Component\\Translation\\Loader\\ArrayLoader` - to load From 629a0086792eff0ffa4b528672e4a63f5dfadd2f Mon Sep 17 00:00:00 2001 From: Raul Fraile Date: Sun, 24 Aug 2014 08:16:49 +0200 Subject: [PATCH 6/8] Extra improvements based on comments --- components/translation/custom_formats.rst | 33 +++++++++++------------ components/translation/introduction.rst | 7 ++--- 2 files changed, 20 insertions(+), 20 deletions(-) diff --git a/components/translation/custom_formats.rst b/components/translation/custom_formats.rst index 18ce1353e39..67bd358cc8a 100644 --- a/components/translation/custom_formats.rst +++ b/components/translation/custom_formats.rst @@ -5,28 +5,28 @@ Custom Formats ============== Sometimes, you need to deal with custom formats for translation files. The -Translation component is flexible enough to support this, just creating a +Translation component is flexible enough to support this. Just create a loader (to load translations) and, optionally, a dumper (to dump translations). -Let's imagine you have a custom format where translation messages are defined -using one line for each translation and parenthesis to wrap the key and the +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)(Bienvenido) - (goodbye)(Adios) + (goodbye)(Adiós) (hello)(Hola) Custom Loader ------------- -To define a custom loader able to read this kind of files, you must create a +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 catalogue that will be returned:: +create the catalog that will be returned:: use Symfony\Component\Translation\MessageCatalogue; use Symfony\Component\Translation\Loader\LoaderInterface; @@ -54,6 +54,8 @@ create the catalogue that will be returned:: Once created, it can be used as any other loader:: + use Symfony\Component\Translation\Translator; + $translator = new Translator('es_ES'); $translator->addLoader('my_format', new MyFormatLoader()); @@ -66,10 +68,11 @@ It will print *"Bienvenido"*. Custom Dumper ------------- -It is also possible to create a custom dumper for your format, useful when using -the extraction commands. To do so, a new class implementing the +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` -interface must be created. + 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:: @@ -79,8 +82,7 @@ will save a few lines:: class MyFormatDumper extends FileDumper { - - public function format(MessageCatalogue $messages, $domain = 'messages') + protected function format(MessageCatalogue $messages, $domain = 'messages') { $output = ''; @@ -100,15 +102,12 @@ will save a few lines:: 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 :class:`Symfony\\Component\\Translation\\Dumper\\FileDumper` class to -create the file. The dumper can be used like any other -built-in dumper. In this example, the translation messages defined in the YAML file -are dumped into a text file with the custom format:: +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; - include_once __DIR__. '/vendor/autoload.php'; - $loader = new YamlFileLoader(); $catalogue = $loader->load(__DIR__ . '/translations/messages.es_ES.yml' , 'es_ES'); diff --git a/components/translation/introduction.rst b/components/translation/introduction.rst index 2d631853fe0..a97e13d7701 100644 --- a/components/translation/introduction.rst +++ b/components/translation/introduction.rst @@ -62,9 +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 -:doc:`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. @@ -96,6 +94,9 @@ default loaders are: All file loaders require the :doc:`Config component `. +You can also :doc:`create your own Loader `, +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``:: // ... From c0f3b0aae58689eb8796980267a198cbe1078ab3 Mon Sep 17 00:00:00 2001 From: Raul Fraile Date: Sun, 24 Aug 2014 08:25:15 +0200 Subject: [PATCH 7/8] Fixed wrong indentation --- components/translation/custom_formats.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/translation/custom_formats.rst b/components/translation/custom_formats.rst index 67bd358cc8a..4ea7574d768 100644 --- a/components/translation/custom_formats.rst +++ b/components/translation/custom_formats.rst @@ -72,7 +72,7 @@ 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. +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:: From 69491ae1736807d1044b5bd3027b5800c7441fbd Mon Sep 17 00:00:00 2001 From: Raul Fraile Date: Tue, 26 Aug 2014 20:44:11 +0200 Subject: [PATCH 8/8] Improved custom formats article based on comments --- components/translation/custom_formats.rst | 31 +++++++++++------------ 1 file changed, 15 insertions(+), 16 deletions(-) diff --git a/components/translation/custom_formats.rst b/components/translation/custom_formats.rst index 4ea7574d768..a212b7b1910 100644 --- a/components/translation/custom_formats.rst +++ b/components/translation/custom_formats.rst @@ -1,8 +1,8 @@ .. index:: - single: Translation; Custom formats + single: Translation; Adding Custom Format Support -Custom Formats -============== +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 @@ -14,12 +14,12 @@ message. A translation file would look like this: .. code-block:: text - (welcome)(Bienvenido) - (goodbye)(Adiós) - (hello)(Hola) + (welcome)(accueil) + (goodbye)(au revoir) + (hello)(bonjour) -Custom Loader -------------- +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 @@ -56,24 +56,23 @@ Once created, it can be used as any other loader:: use Symfony\Component\Translation\Translator; - $translator = new Translator('es_ES'); + $translator = new Translator('fr_FR'); $translator->addLoader('my_format', new MyFormatLoader()); - $translator->addResource('my_format', __DIR__.'/translations/messages.txt', 'es_ES'); + $translator->addResource('my_format', __DIR__.'/translations/messages.txt', 'fr_FR'); echo $translator->trans('welcome'); -It will print *"Bienvenido"*. +It will print *"accueil"*. -Custom Dumper -------------- +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 +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:: @@ -109,7 +108,7 @@ 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.es_ES.yml' , 'es_ES'); + $catalogue = $loader->load(__DIR__ . '/translations/messages.fr_FR.yml' , 'fr_FR'); $dumper = new MyFormatDumper(); $dumper->dump($catalogue, array('path' => __DIR__.'/dumps'));