8000 cleanup alternate locale documentation · symfony-cmf/symfony-cmf-docs@8a91458 · GitHub
[go: up one dir, main page]
Skip to content
This repository was archived by the owner on Sep 16, 2021. It is now read-only.

Commit 8a91458

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

File tree

4 files changed

+51
-217
lines changed

4 files changed

+51
-217
lines changed

‎bundles/seo/alternate_locale.rst

Lines changed: 34 additions & 211 deletions
10000
Original file line numberDiff line numberDiff line change
@@ -1,103 +1,28 @@
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+
Alternate locales are a way of telling search engines how to find translations
5+
of the current page. The SeoBundle provides a way to manage alternate locales
6+
and output them together with the other SEO information.
87

9-
Example
10-
-------
8+
When the alternate locale handling is set up and found alternates, you will
9+
find links like the following in the ``<head>`` part of your HTML pages:
1110

12-
Lets persist a document in three locales.::
13-
14-
// src/Acme/ApplicationBundle/DataFixtures/Doctrine/PHPCR/ExampleFixture.php
15-
16-
<?php
17-
18-
namespace AppBundle\DataFixtures\PHPCR;
19-
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;
25-
26-
/**
27-
* @author Maximilian Berghoff <Maximilian.Berghoff@mayflower.de>
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:
11+
.. code-block: html
9212
9313
<link rel="alternate" href="/fr/le-titre" hreflang="fr" />
9414
<link rel="alternate" href="/de/der-titel" hreflang="de" />
9515
96-
Configuration
97-
-------------
16+
When using PHPCR-ODM, there is almost no work to do, as the bundle can use the
17+
Doctrine meta data to figure out which translations exists for a content. More
18+
information on translating content with the PHPCR-ODM is in the chapter
19+
:doc:`Doctrine PHPCR-ODM Multilanguage Support<../phpcr_odm/multilang>`.
20+
21+
Setting Up Alternate Locale Support
22+
-----------------------------------
9823

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:
24+
Enable alternate locale support. If you are using PHPCR-ODM, also enable
25+
support for that:
10126

10227
.. configuration-block::
10328

@@ -117,140 +42,38 @@ for a given content based on the PHPCR-ODM. You can easily enable that by:
11742
<config xmlns="http://cmf.symfony.com/schema/dic/seo">
11843
<alternate-locale enabled="true" />
11944
<persistence>
120-
<phpcr
121-
enabled="true"
122-
/>
45+
<phpcr enabled="true"/>
12346
</persistence>
12447
</config>
12548
</container>
12649
12750
.. code-block:: php
12851
12952
$container->loadFromExtension('cmf_seo', array(
130-
'alternate_locale' => array (
131-
'enabled' => true,
132-
),
53+
'alternate_locale' => array ('enabled' => true),
13354
'persistence' => array(
13455
'phpcr' => array('enabled' => true),
13556
),
13657
));
13758
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-
}
59+
Rendering Alternate Locales
60+
---------------------------
17461

175-
$alternateLocaleCollection->add(
176-
new AlternateLocale(
177-
$this->urlGenerator->generate($content, array('_locale' => $locale), true),
178-
$locale
179-
)
180-
);
181-
}
62+
The alternate locales are rendered together with the other SEO metadata by the
63+
twig function ``sonata_seo_metadatas``.
18264

183-
return $alternateLocaleCollection;
184-
}
65+
Creating a Custom Alternate Locales Provider
66+
--------------------------------------------
18567

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-
}
199-
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-
));
68+
The default provider serves the routes for the alternate locale contents
69+
directly from the PHPCR-ODM. For other persistence layers or custom needs on
70+
the translated location URLs you can create your own provider by implementing
71+
the ``AlternateLocaleProviderInterface``. To get some inspiration, have a look
72+
at ``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,23 +82,23 @@ 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=< 3D11 span class="pl-pds">"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_loc F438 ale' => array (
278-
'provider_id' => acme.application.alternate_locale.provider,
101+
'provider_id' => 'alternate_locale.provider',
279102
),
280103
));
281104

‎bundles/seo/configuration.rst

Lines changed: 1 addition & 1 deletion
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

‎bundles/seo/introduction.rst

Lines changed: 14 additions & 3 deletions
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
----------

‎bundles/seo/sitemap.rst

Lines changed: 2 additions & 2 deletions
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)
0