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

Commit ba25ca9

Browse files
dbudbu
committed
cleanup alternate locale documentation
1 parent 0b1f039 commit ba25ca9

File tree

4 files changed

+64
-229
lines changed

4 files changed

+64
-229
lines changed

‎bundles/seo/alternate_locale.rst

+43-219
Original file line numberDiff line numberDiff line change
@@ -1,103 +1,30 @@
11
Alternate Locale Handling
22
=========================
33

4-
The CMF provides a powerful way to persist document in different locales.
5-
Each of those translated documents are representations of another. In a
6-
SEO context it would be great to show the available routes to translations
7-
of the current representation.
4+
.. versionadded:: 1.1
5+
Support for handling alternate locales was added in SeoBundle version 1.1.0.
86

9-
Example
10-
-------
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.
1110

12-
Lets persist a document in three locales.::
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:
1313

14-
// src/Acme/ApplicationBundle/DataFixtures/Doctrine/PHPCR/ExampleFixture.php
14+
.. code-block:: html
1515

16-
<?php
16+
<link rel="alternate" href="/fr/le-titre" hreflang="fr">
17+
<link rel="alternate" href="/de/der-titel" hreflang="de">
1718

18-
namespace AppBundle\DataFixtures\PHPCR;
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>`.
1923

20-
use Doctrine\Common\DataFixtures\FixtureInterface;
21-
use Doctrine\Common\Persistence\ObjectManager;
22-
use Doctrine\ODM\PHPCR\DocumentManager;
23-
use Symfony\Cmf\Bundle\ContentBundle\Doctrine\Phpcr\StaticContent;
24-
use Symfony\Cmf\Bundle\RoutingBundle\Doctrine\Phpcr\Route;
24+
Setting Up Alternate Locale Support
25+
-----------------------------------
2526

26-
/**
27-
* @author Maximilian Berghoff <[email protected]>
28-
*/
29-
class ExampleFeature implements FixtureInterface
30-
{
31-
/**
32-
* Load data fixtures with the passed EntityManager
33-
*
34-
* @param DocumentManager|ObjectManager $manager
35-
*/
36-
public function load(ObjectManager $manager)
37-
{
38-
$parent = $manager->find(null, '/cms/routes');
39-
40-
$document = new StaticContent();
41-
$document->setTitle('The Title');
42-
$document->setBody('The body is the main content');
43-
$manager->persist($document);
44-
$manager->bindTranslation($document, 'en');
45-
$route = new Route();
46-
$route->setPosition($parent, 'en');
47-
$route->setCondition($document);
48-
$manager->persist($route);
49-
50-
$document->setTitle('Der Titel');
51-
$document->setBody('Der Body ist der Content');
52-
$manager->bindTranslation($document, 'en');
53-
$route = new Route();
54-
$route->setPosition($parent, 'de');
55-
$route->setCondition($document);
56-
$manager->persist($route);
57-
58-
$document->setTitle('Le titre');
59-
$document->setBody('Le contenu principale');
60-
$manager->bindTranslation($document, 'fr');
61-
$route = new Route();
62-
$route->setPosition($parent, 'fr');
63-
$route->setCondition($document);
64-
$manager->persist($route);
65-
66-
$manager->flush();
67-
}
68-
}
69-
70-
This creates a content document for the languages german, english and french and its routes.
71-
So the routes are persisted as objects, but the content is available under the following urls:
72-
73-
+--------------------+---------------------+
74-
| locale | url |
75-
+================================+=========+
76-
| ``english`` | ``/en/the-title`` |
77-
+--------------------+---------------------+
78-
| ``german`` | ``/de/der-title`` |
79-
+--------------------+---------------------+
80-
| ``french`` | ``/fr/le-titre`` |
81-
+--------------------+---------------------+
82-
83-
- english: /en/
84-
- german: /de/der-titel
85-
86-
.. note::
87-
To get more information about translating content by the PHPCR-ODM have a look
88-
at :doc:`Doctrine PHPCR-ODM Multilanguage Support<../phpcr_odm/multilang>`.
89-
90-
When viewing the page in one language, we would expect hints how to navigate to the others.
91-
Search engines expect the following in the ``<head>`` section of the page:
92-
93-
<link rel="alternate" href="/fr/le-titre" hreflang="fr" />
94-
<link rel="alternate" href="/de/der-titel" hreflang="de" />
95-
96-
Configuration
97-
-------------
98-
99-
The SeoBundle serves a ``AlternateLocaleProvider`` to build alternate locale information
100-
for a given content based on the PHPCR-ODM. You can easily enable that by:
27+
Enable alternate locale support:
10128

10229
.. configuration-block::
10330

@@ -106,151 +33,47 @@ for a given content based on the PHPCR-ODM. You can easily enable that by:
10633
# app/config/config.yml
10734
cmf_seo:
10835
alternate_locale: ~
109-
persistence:
110-
phpcr: ~
11136
11237
.. code-block:: xml
11338
11439
<!-- app/config/config.xml -->
11540
<?xml version="1.0" encoding="UTF-8" ?>
11641
<container xmlns="http://symfony.com/schema/dic/services">
11742
<config xmlns="http://cmf.symfony.com/schema/dic/seo">
118-
<alternate-locale enabled="true" />
119-
<persistence>
120-
<phpcr
121-
enabled="true"
122-
/>
123-
</persistence>
43+
<alternate-locale />
12444
</config>
12545
</container>
12646
12747
.. code-block:: php
12848
12949
$container->loadFromExtension('cmf_seo', array(
130-
'alternate_locale' => array (
131-
'enabled' => true,
132-
),
133-
'persistence' => array(
134-
'phpcr' => array('enabled' => true),
135-
),
50+
'alternate_locale' => true,
13651
));
13752
138-
You have to enable persistence by PHPCR to have the default provider available.
139-
140-
Create your own provider
141-
------------------------
142-
143-
The default provider serves the routes for the alternate locale contents directly from the
144-
PHPCR-ODM. For other persistence layers or custom needs on the translated location URLs you can
145-
create your own provider by implementing the ``AlternateLocaleProviderInterface``::
146-
147-
// src/Acme/ApplicationBundle/AlternateLocaleProvider.php
148-
149-
use Symfony\Cmf\Bundle\SeoBundle\AlternateLocaleProviderInterface;
150-
use Symfony\Cmf\Bundle\SeoBundle\Model\AlternateLocale;
151-
use Symfony\Cmf\Bundle\SeoBundle\Model\AlternateLocaleCollection;
152-
153-
class AlternateLocaleProvider implements AlternateLocaleProviderInterface
154-
{
155-
/**
156-
* Creates a collection of AlternateLocales for one content object.
157-
*
158-
* @param object $content
159-
*
160-
* @return AlternateLocaleCollection
161-
*/
162-
public function createForContent($content)
163-
{
164-
$alternateLocaleCollection = new AlternateLocaleCollection();
165-
// get the alternate locales for the given content
166-
$alternateLocales = $this->getAllForContent($content);
167-
168-
// add the alternate locales except the current one
169-
$currentLocale = $content->getLocale();
170-
foreach ($alternateLocales as $locale) {
171-
if ($locale === $currentLocale) {
172-
continue;
173-
}
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.
17457

175-
$alternateLocaleCollection->add(
176-
new AlternateLocale(
177-
$this->urlGenerator->generate($content, array('_locale' => $locale), true),
178-
$locale
179-
)
180-
);
181-
}
58+
Rendering Alternate Locales
59+
---------------------------
18260

183-
return $alternateLocaleCollection;
184-
}
61+
The alternate locales are rendered together with the other SEO metadata by the
62+
twig function ``sonata_seo_metadatas``.
18563

186-
/**
187-
* Creates a collection of AlternateLocales for many content object.
188-
*
189-
* @param array|object[] $contents
190-
*
191-
* @return AlternateLocaleCollection[]
192-
*/
193-
public function createForContents(array $contents)
194-
{
195-
$result = array();
196-
foreach ($contents as $content) {
197-
$result[] = $this->createForContent($content);
198-
}
64+
Creating a Custom Alternate Locales Provider
65+
--------------------------------------------
19966

200-
return $result;
201-
}
202-
203-
/**
204-
* Creates a list of locales the content is also persisd
205-
*
206-
* @var object $content
207-
* @return array The list of locales
208-
*/
209-
public function getAllForContent($content)
210-
{
211-
$list = array();
212-
// implement you logic
213-
214-
return $list;
215-
}
216-
217-
}
218-
219-
Create a service for your provider:
220-
221-
.. configuration-block::
222-
223-
.. code-block:: yaml
224-
225-
services:
226-
acme.application.alternate_locale.provider
227-
class: "Acme\ApplicationBundle\AlternateLocaleProvider"
228-
229-
.. code-block:: xml
230-
231-
<?xml version="1.0" ?>
232-
233-
<container xmlns="http://symfony.com/schema/dic/services"
234-
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
235-
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
236-
237-
<services>
238-
<service id="acme.application.alternate_locale.provider" class="Acme\ApplicationBundle\AlternateLocaleProvider">
239-
</service>
240-
</services>
241-
242-
</container>
243-
244-
.. code-block:: php
245-
246-
use Symfony\Component\DependencyInjection\Definition;
247-
248-
$container->setDefinition('acme.application.alternate_locale.provider', new Definition(
249-
'Acme\ApplicationBundle\AlternateLocaleProvider'
250-
));
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``.
25173

252-
Now you have to configure ``CmfSeoBundle`` to use your custom alternate locale provider instead of the default one.
253-
Set the ``alternate_locale.provider_id`` to the service you just created:
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:
25477

25578
.. configuration-block::
25679

@@ -259,25 +82,26 @@ Set the ``alternate_locale.provider_id`` to the service you just created:
25982
# app/config/config.yml
26083
cmf_seo:
26184
alternate_locale:
262-
provider_id: acme.application.alternate_locale.provider
85+
provider_id: alternate_locale.provider
26386
26487
.. code-block:: xml
26588
26689
<!-- app/config/config.xml -->
26790
<?xml version="1.0" encoding="UTF-8" ?>
26891
<container xmlns="http://symfony.com/schema/dic/services">
26992
<config xmlns="http://cmf.symfony.com/schema/dic/seo">
270-
<alternate-locale provider-id="acme.application.alternate_locale.provider" />
93+
<alternate-locale provider-id="alternate_locale.provider" />
27194
</config>
27295
</container>
27396
27497
.. code-block:: php
27598
27699
$container->loadFromExtension('cmf_seo', array(
277100
'alternate_locale' => array (
278-
'provider_id' => acme.application.alternate_locale.provider,
101+
'provider_id' => 'alternate_locale.provider',
279102
),
280103
));
281104
282105
.. versionadded:: 1.2
283-
For activated :doc:`Sitemap<sitemap>` the alternate locales will be pushed into the sitemap too.
106+
When :doc:`Sitemaps <sitemap>` are enabled, alternate locales are also
107+
added to the Sitemap.

‎bundles/seo/configuration.rst

+5-5
Original file line numberDiff line numberDiff line change
@@ -358,7 +358,7 @@ routes, use:
358358
~~~~~~~~~~~~~~~~~~~~
359359

360360
.. versionadded:: 1.1
361-
Support for alternate locales were added in version 1.1 of the SeoBundle
361+
Support for alternate locales was added in version 1.1 of the SeoBundle.
362362

363363
.. configuration-block::
364364

@@ -368,15 +368,15 @@ routes, use:
368368
cmf_seo:
369369
alternate_locale:
370370
enabled: true
371-
provider_id: acme.application.alternate_locale.provider
371+
provider_id: app.alternate_locale.provider
372372
373373
.. code-block:: xml
374374
375375
<!-- app/config/config.xml -->
376376
<?xml version="1.0" encoding="UTF-8" ?>
377377
<container xmlns="http://symfony.com/schema/dic/services">
378378
<config xmlns="http://cmf.symfony.com/schema/dic/seo">
379-
<alternate-locale enabled="true" provider-id="acme.application.alternate_locale.provider" />
379+
<alternate-locale enabled="true" provider-id="app.alternate_locale.provider" />
380380
</config>
381381
</container>
382382
@@ -385,7 +385,7 @@ routes, use:
385385
$container->loadFromExtension('cmf_seo', array(
386386
'alternate_locale' => array (
387387
'enabled' => true,
388-
'provider_id' => acme.application.alternate_locale.provider,
388+
'provider_id' => app.alternate_locale.provider,
389389
),
390390
));
391391
@@ -401,4 +401,4 @@ Whether or not the the :ref:`bundles-seo-alternate-locale` should be loaded
401401

402402
**type**: ``string`` **default**: ``null``
403403

404-
Define your a custom :doc:`AlternateLocaleProvider<../seo/alternate_locale>`
404+
Specify the service id of a custom :doc:`AlternateLocaleProvider <../seo/alternate_locale>`.

‎bundles/seo/introduction.rst

+14-3
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
@@ -381,10 +381,21 @@ For changing the default translation domain (messages), you should use the
381381
382382
.. _bundles-seo-alternate-locale:
383383

384-
Alternate locales support
384+
Alternate Locales Support
385385
-------------------------
386386

387-
Tbd.
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`.
388399

389400
Conclusion
390401
----------

0 commit comments

Comments
 (0)