Skip to content

Commit 62fadc5

Browse files
weaverryanweaverryan
committed
Merge branch '2.2' into 2.3
Conflicts: book/translation.rst reference/constraints/Max.rst reference/constraints/MaxLength.rst reference/constraints/Min.rst reference/constraints/MinLength.rst
2 parents d11327b + 210deef commit 62fadc5

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

41 files changed

+989
-639
lines changed

‎book/translation.rst

Lines changed: 224 additions & 583 deletions
Large diffs are not rendered by default.

‎components/dependency_injection/parameters.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -333,9 +333,9 @@ Yaml
333333
Start the string with ``@`` or ``@?`` to reference a service in Yaml.
334334

335335
* ``@mailer`` references the ``mailer`` service. If the service does not
336-
exists, an exception will be thrown;
336+
exist, an exception will be thrown;
337337
* ``@?mailer`` references the ``mailer`` service. If the service does not
338-
exists, it will be ignored;
338+
exist, it will be ignored;
339339

340340
.. tip::
341341

‎components/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ The Components
2727
serializer
2828
stopwatch
2929
templating/index
30+
translation/index
3031
yaml/index
3132

3233
.. include:: /components/map.rst.inc

‎components/map.rst.inc

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -122,6 +122,11 @@
122122

123123
* :doc:`/components/templating/introduction`
124124

125+
* :doc:`/components/translation/index`
126+
127+
* :doc:`/components/translation/introduction`
128+
* :doc:`/components/translation/usage`
129+
125130
* :doc:`/components/yaml/index`
126131

127132
* :doc:`/components/yaml/introduction`

‎components/translation/index.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
Translation
2+
===========
3+
4+
.. toctree::
5+
:maxdepth: 2
6+
7+
introduction
8+
usage

‎components/translation/introduction.rst

Lines changed: 210 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,210 @@
1+
.. index::
2+
single: Translation
3+
single: Components; Translation
4+
5+
The Translation Component
6+
=========================
7+
8+
The Translation component provides tools to internationalize your
9+
application.
10+
11+
Installation
12+
------------
13+
14+
You can install the component in 2 different ways:
15+
16+
* :doc:`Install it via Composer</components/using_components>` (``symfony/translation`` on `Packagist`_).
17+
* Use the official Git repository (https://github.com/symfony/Translation);
18+
19+
Constructing the Translator
20+
---------------------------
21+
22+
The main access point of the Translation Component is
23+
:class:`Symfony\\Component\\Translation\\Translator`. Before you can use it,
24+
you need to configure it and load the messages to translate (called *message
25+
catalogs*).
26+
27+
Configuration
28+
~~~~~~~~~~~~~
29+
30+
The constructor of the ``Translator`` class needs one argument: The locale.
31+
32+
.. code-block:: php
33+
34+
use Symfony\Component\Translation\Translator;
35+
use Symfony\Component\Translation\MessageSelector;
36+
37+
$translator = new Translator('fr_FR', new MessageSelector());
38+
39+
.. note::
40+
41+
The locale set here is the default locale to use. You can override this
42+
locale when translating strings.
43+
44+
.. note::
45+
46+
The term *locale* refers roughly to the user's language and country. It
47+
can be any string that your application uses to manage translations and
48+
other format differences (e.g. currency format). The `ISO639-1`_
49+
*language* code, an underscore (``_``), then the `ISO3166 Alpha-2`_
50+
*country* code (e.g. ``fr_FR`` for French/France) is recommended.
51+
52+
.. _component-translator-message-catalogs:
53+
54+
Loading Message Catalogs
55+
~~~~~~~~~~~~~~~~~~~~~~~~
56+
57+
The messages are stored in message catalogs inside the ``Translator``
58+
class. A message catalog is like a dictionary of translations for a specific
59+
locale.
60+
61+
The Translation component uses Loader classes to load catalogs. You can load
62+
multiple resources for the same locale, it will be combined into one
63+
catalog.
64+
65+
The component comes with some default Loaders and you can create your own
66+
Loader too. The default loaders are:
67+
68+
* :class:`Symfony\\Component\\Translation\\Loader\\ArrayLoader` - to load
69+
catalogs from PHP arrays.
70+
* :class:`Symfony\\Component\\Translation\\Loader\\CsvFileLoader` - to load
71+
catalogs from CSV files.
72+
* :class:`Symfony\\Component\\Translation\\Loader\\IcuDatFileLoader` - to load
73+
catalogs form resource bundles.
74+
* :class:`Symfony\\Component\\Translation\\Loader\\IcuResFileLoader` - to load
75+
catalogs form resource bundles.
76+
* :class:`Symfony\\Component\\Translation\\Loader\\IniFileLoader` - to load
77+
catalogs form ini files.
78+
* :class:`Symfony\\Component\\Translation\\Loader\\MoFileLoader` - to load
79+
catalogs form gettext files.
80+
* :class:`Symfony\\Component\\Translation\\Loader\\PhpFileLoader` - to load
81+
catalogs from PHP files.
82+
* :class:`Symfony\\Component\\Translation\\Loader\\PoFileLoader` - to load
83+
catalogs form gettext files.
84+
* :class:`Symfony\\Component\\Translation\\Loader\\QtFileLoader` - to load
85+
catalogs form QT XML files.
86+
* :class:`Symfony\\Component\\Translation\\Loader\\XliffFileLoader` - to load
87+
catalogs from Xliff files.
88+
* :class:`Symfony\\Component\\Translation\\Loader\\YamlFileLoader` - to load
89+
catalogs from Yaml files (requires the :doc:`Yaml component</components/yaml>`).
90+
91+
.. versionadded:: 2.1
92+
The ``IcuDatFileLoader``, ``IcuResFileLoader``, ``IniFileLoader``,
93+
``MofileLoader``, ``PoFileLoader`` and ``QtFileLoader`` are new in
94+
Symfony 2.1
95+
96+
All file loaders require the :doc:`Config component</components/config/index>`.
97+
98+
At first, you should add one or more loaders to the ``Translator``::
99+
100+
// ...
101+
$translator->addLoader('array', new ArrayLoader());
102+
103+
The first argument is the name to which you can refer the loader in the
104+
translator and the second argument is an instance of the loader itself. After
105+
this, you can add your resources using the correct loader.
106+
107+
Loading Messages with the ``ArrayLoader``
108+
.........................................
109+
110+
Loading messages can be done by calling
111+
:method:`Symfony\\Component\\Translation\\Translator::addResource`. The first
112+
argument is the loader name (this was the first argument of the ``addLoader``
113+
method), the second is the resource and the third argument is the locale::
114+
115+
// ...
116+
$translator->addResource('array', array(
117+
'Hello World!' => 'Bonjour',
118+
), 'fr_FR');
119+
120+
Loading Messages with the File Loaders
121+
......................................
122+
123+
If you use one of the file loaders, you should also use the ``addResource``
124+
method. The only difference is that you should put the file name to the resource
125+
file as the second argument, instead of an array::
126+
127+
// ...
128+
$translator->addLoader('yaml', new YamlFileLoader());
129+
$translator->addResource('yaml', 'path/to/messages.fr.yml', 'fr_FR');
130+
131+
The Translation Process
132+
-----------------------
133+
134+
To actually translate the message, the Translator uses a simple process:
135+
136+
* A catalog of translated messages is loaded from translation resources defined
137+
for the ``locale`` (e.g. ``fr_FR``). Messages from the
138+
:ref:`components-fallback-locales` are also loaded and added to the
139+
catalog, if they don't already exist. The end result is a large "dictionary"
140+
of translations;
141+
142+
* If the message is located in the catalog, the translation is returned. If
143+
not, the translator returns the original message.
144+
145+
You start this process by calling
146+
:method:`Symfony\\Component\\Translation\\Translator::trans` or
147+
:method:`Symfony\\Component\\Translation\\Translator::transChoice`. Then, the
148+
Translator looks for the exact string inside the appropriate message catalog
149+
and returns it (if it exists).
150+
151+
.. _components-fallback-locales:
152+
153+
Fallback Locales
154+
~~~~~~~~~~~~~~~~
155+
156+
If the message is not located in the catalog of the specific locale, the
157+
translator will look into the catalog of one or more fallback locales. For
158+
example, assume you're trying to translate into the ``fr_FR`` locale:
159+
160+
1. First, the translator looks for the translation in the ``fr_FR`` locale;
161+
162+
2. If it wasn't found, the translator looks for the translation in the ``fr``
163+
locale;
164+
165+
3. If the translation still isn't found, the translator uses the one or more
166+
fallback locales set explicitly on the translator.
167+
168+
For (3), the fallback locales can be set by calling
169+
:method:`Symfony\\Component\\Translation\\Translator::setFallbackLocale`::
170+
171+
// ...
172+
$translator->setFallbackLocale(array('en'));
173+
174+
.. _using-message-domains:
175+
176+
Using Message Domains
177+
---------------------
178+
179+
As you've seen, message files are organized into the different locales that
180+
they translate. The message files can also be organized further into "domains".
181+
182+
The domain is specified in the fourth argument of the ``addResource()``
183+
method. The default domain is ``messages``. For example, suppose that, for
184+
organization, translations were split into three different domains:
185+
``messages``, ``admin`` and ``navigation``. The French translation would be
186+
loaded like this::
187+
188+
// ...
189+
$translator->addLoader('xliff', new XliffLoader());
190+
191+
$translator->addResource('xliff', 'messages.fr.xliff', 'fr_FR');
192+
$translator->addResource('xliff', 'admin.fr.xliff', 'fr_FR', 'admin');
193+
$translator->addResource('xliff', 'navigation.fr.xliff', 'fr_FR', 'navigation');
194+
195+
When translating strings that are not in the default domain (``messages``),
196+
you must specify the domain as the third argument of ``trans()``::
197+
198+
$translator->trans('Symfony2 is great', array(), 'admin');
199+
200+
Symfony2 will now look for the message in the ``admin`` domain of the
201+
specified locale.
202+
203+
Usage
204+
-----
205+
206+
Read how to use the Translation component in ":doc:`/components/translation/usage`".
207+
208+
.. _Packagist: https://packagist.org/packages/symfony/translation
209+
.. _`ISO3166 Alpha-2`: http://en.wikipedia.org/wiki/ISO_3166-1#Current_codes
210+
.. _`ISO639-1`: http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes

0 commit comments

Comments
 (0)