Skip to content

Updated the translation/* articles to Symfony 4 #8733

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Nov 27, 2017
Merged

Updated the translation/* articles to Symfony 4 #8733

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8fe3cf0
Updated the translation/* articles to Symfony 4
javiereguiluz Nov 22, 2017
aec8b0e
Tweaks
javiereguiluz Nov 23, 2017
eb93259
Fixes after Ryan's remarks
javiereguiluz Nov 27, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file removed _images/translation/debug_1.png
View file
Open in desktop
Binary file not shown.
Binary file removed _images/translation/debug_2.png
View file
Open in desktop
Binary file not shown.
Binary file removed _images/translation/debug_3.png
View file
Open in desktop
Binary file not shown.
Binary file removed _images/translation/debug_4.png
View file
Open in desktop
Binary file not shown.
80 changes: 48 additions & 32 deletions translation.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,24 +48,37 @@ to learn even more. Overall, the process has several steps:

.. _translation-configuration:

Installation
------------

In applications using :doc:`Symfony Flex </setup/flex>`, run this command to
install the translator before using it:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not mentioning this in 4.0: I'm assuming they have Flex installed and have that dir structure. If we don't assume this, then the docs become a mess.


.. code-block:: terminal

$ composer require translator

Configuration
-------------

Translations are handled by a ``translator`` service that uses the user's
locale to lookup and return translated messages. Before using it, enable the
``translator`` in your configuration:
The previous creates an initial config file where you can define the default
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The previous command...

locale of the app and the :ref:`fallback locales <translation-fallback>` used
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

... fallback locales that will be used if Symfony...

when Symfony can't find some translation:

.. configuration-block::

.. code-block:: yaml

# app/config/config.yml
# config/packages/translation.yaml
framework:
translator: { fallbacks: [en] }
default_locale: 'en'
translator:
fallbacks: ['en']
# ...

.. code-block:: xml

<!-- app/config/config.xml -->
<!-- config/packages/translation.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
Expand All @@ -75,23 +88,23 @@ locale to lookup and return translated messages. Before using it, enable the
http://symfony.com/schema/dic/symfony
http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">

<framework:config>
<framework:config default-locale="en">
<framework:translator>
<framework:fallback>en</framework:fallback>
<!-- ... -->
</framework:translator>
</framework:config>
</container>

.. code-block:: php

// app/config/config.php
// config/packages/translation.php
$container->loadFromExtension('framework', array(
'default_locale' => 'en',
'translator' => array('fallbacks' => array('en')),
// ...
));

See :ref:`translation-fallback` for details on the ``fallbacks`` key
and what Symfony does when it doesn't find a translation.

The locale used in translations is the one stored on the request. This is
typically set via a ``_locale`` attribute on your routes (see :ref:`translation-locale-url`).

Expand All @@ -108,10 +121,11 @@ for example, that you're translating a simple message from inside a controller::

// ...
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Translation\Translator;

public function indexAction()
public function index(Translator $translator)
{
$translated = $this->get('translator')->trans('Symfony is great');
$translated = $translator->trans('Symfony is great');

return new Response($translated);
}
Expand All @@ -129,7 +143,7 @@ different formats, XLIFF being the recommended format:

.. code-block:: xml

<!-- messages.fr.xlf -->
<!-- translations/messages.fr.xlf -->
<?xml version="1.0"?>
<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
<file source-language="en" datatype="plaintext" original="file.ext">
Expand All @@ -144,12 +158,12 @@ different formats, XLIFF being the recommended format:

.. code-block:: yaml

# messages.fr.yml
# translations/messages.fr.yml
Symfony is great: J'aime Symfony

.. code-block:: php

// messages.fr.php
// translations/messages.fr.php
return array(
'Symfony is great' => 'J\'aime Symfony',
);
Expand Down Expand Up @@ -186,10 +200,11 @@ Message Placeholders
Sometimes, a message containing a variable needs to be translated::

use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Translation\Translator;

public function indexAction($name)
public function index(Translator $translator, $name)
{
$translated = $this->get('translator')->trans('Hello '.$name);
$translated = $translator->trans('Hello '.$name);

return new Response($translated);
}
Expand Down Expand Up @@ -336,14 +351,14 @@ Translation Resource/File Names and Locations

Symfony looks for message files (i.e. translations) in the following default locations:

* the ``app/Resources/translations`` directory;
* the ``translations/`` directory;

* the ``app/Resources/<bundle name>/translations`` directory;
* the ``src/Resources/<bundle name>/translations/`` directory;

* the ``Resources/translations/`` directory inside of any bundle.

The locations are listed here with the highest priority first. That is, you can
override the translation messages of a bundle in any of the top 2 directories.
override the translation messages of a bundle in any of the top two directories.

The override mechanism works at a key level: only the overridden keys need
to be listed in a higher priority message file. When a key is not found
Expand All @@ -359,14 +374,14 @@ must be named according to the following path: ``domain.locale.loader``:
* **locale**: The locale that the translations are for (e.g. ``en_GB``, ``en``, etc);

* **loader**: How Symfony should load and parse the file (e.g. ``xlf``,
``php``, ``yml``, etc).
``php``, ``yaml``, etc).

The loader can be the name of any registered loader. By default, Symfony
provides many loaders, including:

* ``xlf``: XLIFF file;
* ``php``: PHP file;
* ``yml``: YAML file.
* ``yaml``: YAML file.

The choice of which loader to use is entirely up to you and is a matter of
taste. The recommended option is to use ``xlf`` for translations.
Expand All @@ -381,15 +396,15 @@ For more options, see :ref:`component-translator-message-catalogs`.

.. code-block:: yaml

# app/config/config.yml
# config/packages/translation.yaml
framework:
translator:
paths:
- '%kernel.project_dir%/translations'
- '%kernel.project_dir%/custom/path/to/translations'

.. code-block:: xml

<!-- app/config/config.xml -->
<!-- config/packages/translation.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:framework="http://symfony.com/schema/dic/symfony"
Expand All @@ -402,18 +417,18 @@ For more options, see :ref:`component-translator-message-catalogs`.

<framework:config>
<framework:translator>
<framework:path>%kernel.project_dir%/translations</framework:path>
<framework:path>%kernel.project_dir%/custom/path/to/translations</framework:path>
</framework:translator>
</framework:config>
</container>

.. code-block:: php

// app/config/config.php
// config/packages/translation.php
$container->loadFromExtension('framework', array(
'translator' => array(
'paths' => array(
'%kernel.project_dir%/translations',
'%kernel.project_dir%/custom/path/to/translations',
),
),
));
Expand Down Expand Up @@ -455,7 +470,7 @@ checks translation resources for several locales:

.. note::

When Symfony doesn't find a translation in the given locale, it will
When Symfony can't find a translation in the given locale, it will
add the missing translation to the log file. For details,
see :ref:`reference-framework-translator-logging`.

Expand Down Expand Up @@ -504,9 +519,10 @@ Learn more

.. toctree::
:maxdepth: 1
:glob:

/translation/*
translation/locale
translation/debug
translation/lint

.. _`i18n`: https://en.wikipedia.org/wiki/Internationalization_and_localization
.. _`ISO 3166-1 alpha-2`: https://en.wikipedia.org/wiki/ISO_3166-1#Current_codes
Expand Down
Loading