Skip to content
This repository was archived by the owner on Sep 16, 2021. It is now read-only.

Commit 74b48a2

Browse files
dbudbu
committed
Merge pull request #755 from symfony-cmf/alternate_locale_handling
Document alternate locale handling
2 parents 853b25b + dec1ebf commit 74b48a2

File tree

5 files changed

+178
-3
lines changed

5 files changed

+178
-3
lines changed

‎bundles/seo/alternate_locale.rst

+107
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
Alternate Locale Handling
2+
=========================
3+
4+
.. versionadded:: 1.1
5+
Support for handling alternate locales was added in SeoBundle version 1.1.0.
6+
7+
Alternate locales are a way of telling search engines how to find translations
8+
of the current page. The SeoBundle provides a way to manage alternate locales
9+
and render them together with the other SEO information.
10+
11+
When the alternate locale handling is set up and found alternates, you will
12+
find links like the following in the ``<head>`` part of your HTML pages:
13+
14+
.. code-block:: html
15+
16+
<link rel="alternate" href="/fr/le-titre" hreflang="fr">
17+
<link rel="alternate" href="/de/der-titel" hreflang="de">
18+
19+
When using PHPCR-ODM, there is almost no work to do, as the bundle can use the
20+
Doctrine meta data to figure out which translations exists for a content. More
21+
information on translating content with the PHPCR-ODM is in the chapter
22+
:doc:`Doctrine PHPCR-ODM Multilanguage Support <../phpcr_odm/multilang>`.
23+
24+
Setting Up Alternate Locale Support
25+
-----------------------------------
26+
27+
Enable alternate locale support:
28+
29+
.. configuration-block::
30+
31+
.. code-block:: yaml
32+
33+
# app/config/config.yml
34+
cmf_seo:
35+
alternate_locale: ~
36+
37+
.. code-block:: xml
38+
39+
<!-- app/config/config.xml -->
40+
<?xml version="1.0" encoding="UTF-8" ?>
41+
<container xmlns="http://symfony.com/schema/dic/services">
42+
<config xmlns="http://cmf.symfony.com/schema/dic/seo">
43+
<alternate-locale />
44+
</config>
45+
</container>
46+
47+
.. code-block:: php
48+
49+
$container->loadFromExtension('cmf_seo', array(
50+
'alternate_locale' => true,
51+
));
52+
53+
If you are using PHPCR-ODM, enabling ``phpcr: ~`` in the seo bundle
54+
configuration will activate a listener that extracts the alternate locales
55+
from the PHPCR-ODM meta data. For other storage systems, you will need to
56+
write a provider and configure the bundle to use that provider - see below.
57+
58+
Rendering Alternate Locales
59+
---------------------------
60+
61+
The alternate locales are rendered together with the other SEO metadata by the
62+
twig function ``sonata_seo_metadatas``.
63+
64+
Creating a Custom Alternate Locales Provider
65+
--------------------------------------------
66+
67+
The alternate locale provider is asked to provide translated URLs for a content
68+
object. The bundle comes with a provider for PHPCR-ODM. For other persistence
69+
layers or custom requirements on the translated URLs you need to create your
70+
own provider implementing the ``AlternateLocaleProviderInterface``. For some
71+
inspiration, have a look at
72+
``Symfony\Cmf\Bundle\SeoBundle\Doctrine\Phpcr\AlternateLocaleProvider``.
73+
74+
Define a service for your provider, so that you can configure the seo bundle to
75+
use your custom alternate locale provider instead of the default one. Set the
76+
``alternate_locale.provider_id`` to the service you just created:
77+
78+
.. configuration-block::
79+
80+
.. code-block:: yaml
81+
82+
# app/config/config.yml
83+
cmf_seo:
84+
alternate_locale:
85+
provider_id: alternate_locale.provider
86+
87+
.. code-block:: xml
88+
89+
<!-- app/config/config.xml -->
90+
<?xml version="1.0" encoding="UTF-8" ?>
91+
<container xmlns="http://symfony.com/schema/dic/services">
92+
<config xmlns="http://cmf.symfony.com/schema/dic/seo">
93+
<alternate-locale provider-id="alternate_locale.provider" />
94+
</config>
95+
</container>
96+
97+
.. code-block:: php
98+
99+
$container->loadFromExtension('cmf_seo', array(
100+
'alternate_locale' => array (
101+
'provider_id' => 'alternate_locale.provider',
102+
),
103+
));
104+
105+
.. versionadded:: 1.2
106+
When :doc:`Sitemaps <sitemap>` are enabled, alternate locales are also
107+
added to the Sitemap.

‎bundles/seo/configuration.rst

+49
Original file line numberDiff line numberDiff line change
@@ -353,3 +353,52 @@ routes, use:
353353
),
354354
),
355355
));
356+
357+
``alternate_locale``
358+
~~~~~~~~~~~~~~~~~~~~
359+
360+
.. versionadded:: 1.1
361+
Support for alternate locales was added in version 1.1 of the SeoBundle.
362+
363+
.. configuration-block::
364+
365+
.. code-block:: yaml
366+
367+
# app/config/config.yml
368+
cmf_seo:
369+
alternate_locale:
370+
enabled: true
371+
provider_id: app.alternate_locale.provider
372+
373+
.. code-block:: xml
374+
375+
<!-- app/config/config.xml -->
376+
<?xml version="1.0" encoding="UTF-8" ?>
377+
<container xmlns="http://symfony.com/schema/dic/services">
378+
<config xmlns="http://cmf.symfony.com/schema/dic/seo">
379+
<alternate-locale enabled="true" provider-id="app.alternate_locale.provider" />
380+
</config>
381+
</container>
382+
383+
.. code-block:: php
384+
385+
$container->loadFromExtension('cmf_seo', array(
386+
'alternate_locale' => array (
387+
'enabled' => true,
388+
'provider_id' => app.alternate_locale.provider,
389+
),
390+
));
391+
392+
``enabled``
393+
"""""""""""
394+
395+
**type**: ``boolean`` **default**: ``true``
396+
397+
Whether or not the the :ref:`bundles-seo-alternate-locale` should be loaded
398+
399+
``provider_id``
400+
"""""""""""""""
401+
402+
**type**: ``string`` **default**: ``null``
403+
404+
Specify the service id of a custom :doc:`AlternateLocaleProvider <../seo/alternate_locale>`.

‎bundles/seo/index.rst

+1
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ SeoBundle
88
seo_aware
99
extractors
1010
sitemap
11+
alternate_locale
1112
error_pages
1213
configuration
1314
twig

‎bundles/seo/introduction.rst

+19-1
Original file line numberDiff line numberDiff line change
@@ -145,7 +145,7 @@ The Twig Extension
145145
The twig extension was added in SeoBundle 1.2.
146146

147147
This bundle provides a twig function ``cmf_seo_update_metadata``
148-
which lets you populate the seo page from an object.
148+
which lets you populate the seo page from an object.
149149
For details on using the twig extension, read :doc:`twig`.
150150

151151
Extracting Metadata
@@ -379,6 +379,24 @@ For changing the default translation domain (messages), you should use the
379379
),
380380
);
381381
382+
.. _bundles-seo-alternate-locale:
383+
384+
Alternate Locales Support
385+
-------------------------
386+
387+
Alternate locales are a way of telling search engines how to find translations
388+
of the current page. The SeoBundle provides a way to manage alternate locales
389+
and output them together with the other SEO information.
390+
391+
This feature is explained in :doc:`alternate_locale`.
392+
393+
Sitemap Support
394+
---------------
395+
396+
The SEO bundle can help you provide XML sitemaps to be consumed by search engines.
397+
398+
This feature is explained in :doc:`sitemap`.
399+
382400
Conclusion
383401
----------
384402

‎bundles/seo/sitemap.rst

+2-2
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,8 @@ the information from them and rendering them to a sitemap information.
1010
You can generate sitemaps in different formats and it is possible to provide
1111
more than one set of configurations.
1212

13-
Setting Up the Bundle
14-
---------------------
13+
Setting Up Sitemap Support
14+
--------------------------
1515

1616
You need to register the route for the controller that is serving sitemaps:
1717

0 commit comments

Comments
 (0)