10000 feature #4166 Translation custom loaders (raulfraile) · symfony/symfony-docs@a8dc2bf · GitHub
[go: up one dir, main page]
Skip to content

Commit a8dc2bf

Browse files
weaverryanweaverryan
committed
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
2 parents 2cf9e47 + 69491ae commit a8dc2bf

File tree

4 files changed

+120
-2
lines changed

4 files changed

+120
-2
lines changed

‎components/map.rst.inc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -130,6 +130,7 @@
130130

131131
* :doc:`/components/translation/introduction`
132132
* :doc:`/components/translation/usage`
133+
* :doc:`/components/translation/custom_formats`
133134

134135
* :doc:`/components/yaml/index`
135136

‎components/translation/custom_formats.rst

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
.. index::
2+
single: Translation; Adding Custom Format Support
3+
4+
Adding Custom Format Support
5+
============================
6+
7+
Sometimes, you need to deal with custom formats for translation files. The
8+
Translation component is flexible enough to support this. Just create a
9+
loader (to load translations) and, optionally, a dumper (to dump translations).
10+
11+
Imagine that you have a custom format where translation messages are defined
12+
using one line for each translation and parentheses to wrap the key and the
13+
message. A translation file would look like this:
14+
15+
.. code-block:: text
16+
17+
(welcome)(accueil)
18+
(goodbye)(au revoir)
19+
(hello)(bonjour)
20+
21+
Creating a Custom Loader
22+
------------------------
23+
24+
To define a custom loader that is able to read this kind of files, you must create a
25+
new class that implements the
26+
:class:`Symfony\\Component\\Translation\\Loader\\LoaderInterface`. The
27+
:method:`Symfony\\Component\\Translation\\Loader\\LoaderInterface::load`
28+
method will get a filename and parse it into an array. Then, it will
29+
create the catalog that will be returned::
30+
31+
use Symfony\Component\Translation\MessageCatalogue;
32+
use Symfony\Component\Translation\Loader\LoaderInterface;
33+
34+
class MyFormatLoader implements LoaderInterface
35+
{
36+
public function load($resource, $locale, $domain = 'messages')
37+
{
38+
$messages = array();
39+
$lines = file($resource);
40+
41+
foreach ($lines as $line) {
42+
if (preg_match('/\(([^\)]+)\)\(([^\)]+)\)/', $line, $matches)) {
43+
$messages[$matches[1]] = $matches[2];
44+
}
45+
}
46+
47+
$catalogue = new MessageCatalogue($locale);
48+
$catalogue->add($messages, $domain);
49+
50+
return $catalogue;
51+
}
52+
53+
}
54+
55+
Once created, it can be used as any other loader::
56+
57+
use Symfony\Component\Translation\Translator;
58+
59+
$translator = new Translator('fr_FR');
60+
$translator->addLoader('my_format', new MyFormatLoader());
61+
62+
$translator->addResource('my_format', __DIR__.'/translations/messages.txt', 'fr_FR');
63+
64+
echo $translator->trans('welcome');
65+
66+
It will print *"accueil"*.
67+
68+
Creating a Custom Dumper
69+
------------------------
70+
71+
It is also possible to create a custom dumper for your format, which is
72+
useful when using the extraction commands. To do so, a new class
73+
implementing the
74+
:class:`Symfony\\Component\\Translation\\Dumper\\DumperInterface`
75+
must be created. To write the dump contents into a file, extending the
76+
:class:`Symfony\\Component\\Translation\\Dumper\\FileDumper` class
77+
will save a few lines::
78+
79+
use Symfony\Component\Translation\MessageCatalogue;
80+
use Symfony\Component\Translation\Dumper\FileDumper;
81+
82+
class MyFormatDumper extends FileDumper
83+
{
84+
protected function format(MessageCatalogue $messages, $domain = 'messages')
85+
{
86+
$output = '';
87+
88+
foreach ($messages->all($domain) as $source => $target) {
89+
$output .= sprintf("(%s)(%s)\n", $source, $target);
90+
}
91+
92+
return $output;
93+
}
94+
95+
protected function getExtension()
96+
{
97+
return 'txt';
98+
}
99+
}
100+
101+
The :method:`Symfony\\Component\\Translation\\Dumper\\FileDumper::format`
102+
method creates the output string, that will be used by the
103+
:method:`Symfony\\Component\\Translation\\Dumper\\FileDumper::dump` method
104+
of the FileDumper class to create the file. The dumper can be used like any other
105+
built-in dumper. In the following example, the translation messages defined in the
106+
YAML file are dumped into a text file with the custom format::
107+
108+
use Symfony\Component\Translation\Loader\YamlFileLoader;
109+
110+
$loader = new YamlFileLoader();
111+
$catalogue = $loader->load(__DIR__ . '/translations/messages.fr_FR.yml' , 'fr_FR');
112+
113+
$dumper = new MyFormatDumper();
114+
$dumper->dump($catalogue, array('path' => __DIR__.'/dumps'));

‎components/translation/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,4 @@ Translation
66

77
introduction
88
usage
9+
custom_formats

‎components/translation/introduction.rst

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -62,8 +62,7 @@ The Translation component uses Loader classes to load catalogs. You can load
6262
multiple resources for the same locale, which will then be combined into one
6363
catalog.
6464

65-
The component comes with some default Loaders and you can create your own
66-
Loader too. The default loaders are:
65+
The component comes with some default loaders:
6766

6867
* :class:`Symfony\\Component\\Translation\\Loader\\ArrayLoader` - to load
6968
catalogs from PHP arrays.
@@ -95,6 +94,9 @@ Loader too. The default loaders are:
9594

9695
All file loaders require the :doc:`Config component </components/config/index>`.
9796

97+
You can also :doc:`create your own Loader </components/translation/custom_formats>`,
98+
in case the format is not already supported by one of the default loaders.
99+
98100
At first, you should add one or more loaders to the ``Translator``::
99101

100102
// ...

0 commit comments

Comments
 (0)
0