move i18n ZCML topics to declarative chapter

2 files changed, 81 insertions, 76 deletions

diff --git a/docs/narr/declarative.rst b/docs/narr/declarative.rst
index 85b527f3d..23ad63d2f 100644
--- a/docs/narr/declarative.rst
+++ b/docs/narr/declarative.rst
@@ -1089,11 +1089,48 @@ tag):
 See also :ref:`renderer_directive` and
 :meth:`pyramid.configuration.Configurator.add_renderer`.
 
+.. _zcml_adding_a_translation_directory:
+
+Adding a Translation Directory via ZCML
+---------------------------------------
+
+You can add a translation directory via ZCML by using the
+:ref:`translationdir_directive` ZCML directive:
+
+.. code-block:: xml
+   :linenos:
+
+   <translationdir dir="my.application:locale/"/>
+
+A message catalog in a translation directory added via
+:ref:`translationdir_directive` will be merged into translations from
+a message catalog added earlier if both translation directories
+contain translations for the same locale and :term:`translation
+domain`.
+
+See also :ref:`translationdir_directive` and
+:ref:`adding_a_translation_directory`.
+
+.. _zcml_adding_a_locale_negotiator:
+
+Adding a Custom Locale Negotiator via ZCML
+------------------------------------------
+
+You can add a custom locale negotiator via ZCML by using the
+:ref:`localenegotiator_directive` ZCML directive:
+
+.. code-block:: xml
+   :linenos:
+
+    <localenegotiator 
+       negotiator="my_application.my_module.my_locale_negotiator"/>
+
+See also :ref:`custom_locale_negotiator` and
+:ref:`localenegotiator_directive`.
+
 .. Todo
 .. ----
 
-.. - i18n chapter still has topics for ZCML
-
 .. - events chapter still has topics for ZCML
 
 .. - hooks chapter still has topics for ZCML
diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst
index aaa1962e8..a7b952019 100644
--- a/docs/narr/i18n.rst
+++ b/docs/narr/i18n.rst
@@ -845,6 +845,8 @@ To turn translation on, you must:
 
 - ensure that your application sets the :term:`locale name` correctly.
 
+.. _adding_a_translation_directory:
+
 Adding a Translation Directory
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -863,48 +865,28 @@ found within all ``LC_MESSAGES`` directories within each locale
 directory in the translation directory) within your :mod:`pyramid`
 application to be available to use for translation services.
 
-You may add a translation directory to your application's
-configuration using either imperative configuration or ZCML.
-
-.. topic:: Using Imperative Configuration
-
-    You can add a translation directory imperatively by using the
-    :meth:`pyramid.configuration.Configurator.add_translation_dirs`
-    during application startup.
-
-    For example:
-
-    .. code-block:: python
-       :linenos:
-
-       from pyramid.configuration import Configurator
-       config.begin()
-       config.add_translation_dirs('my.application:locale/', 
-                                   'another.application:locale/')
-       ...
-       config.end()
-
-    A message catalog in a translation directory added via
-    :meth:`pyramid.configuration.Configurator.add_translation_dirs`
-    will be merged into translations from a message catalog added earlier
-    if both translation directories contain translations for the same
-    locale and :term:`translation domain`.
-
-.. topic:: Using ZCML
+You can add a translation directory imperatively by using the
+:meth:`pyramid.configuration.Configurator.add_translation_dirs` during
+application startup.  For example:
 
-    You can add a translation directory via ZCML by using the
-    :ref:`translationdir_directive` ZCML directive:
+.. code-block:: python
+   :linenos:
 
-    .. code-block:: xml
-       :linenos:
+   from pyramid.configuration import Configurator
+   config.begin()
+   config.add_translation_dirs('my.application:locale/', 
+                               'another.application:locale/')
+   ...
+   config.end()
 
-       <translationdir dir="my.application:locale/"/>
+A message catalog in a translation directory added via
+:meth:`pyramid.configuration.Configurator.add_translation_dirs`
+will be merged into translations from a message catalog added earlier
+if both translation directories contain translations for the same
+locale and :term:`translation domain`.
 
-    A message catalog in a translation directory added via
-    :ref:`translationdir_directive` will be merged into translations from
-    a message catalog added earlier if both translation directories
-    contain translations for the same locale and :term:`translation
-    domain`.
+.. note:: You can also add a translation directory via ZCML.  See
+   :ref:`zcml_adding_a_translation_directory`
 
 Setting the Locale
 ~~~~~~~~~~~~~~~~~~
@@ -1007,46 +989,32 @@ If a locale negotiator returns ``None``, it signifies to
 used.
 
 You may add your newly created locale negotiator to your application's
-configuration using either imperative configuration or ZCML.
+configuration by passing an object which can act as the negotiator (or a
+:term:`dotted Python name` referring to the object) as the
+``locale_negotiator`` argument of the
+:class:`pyramid.configuration.Configurator` instance during application
+startup.  For example:
 
-.. topic:: Using Imperative Configuration
-
-    Pass an object which can act as the negotiator (or a :term:`dotted
-    Python name` referring to the object) as the ``locale_negotiator``
-    argument of the :class:`pyramid.configuration.Configurator`
-    instance during application startup.
-
-    For example:
-
-    .. code-block:: python
-       :linenos:
-
-       from pyramid.configuration import Configurator
-       config = Configurator(locale_negotiator=my_locale_negotiator)
-
-    Alternately, use the
-    :meth:`pyramid.configuration.Configurator.set_locale_negotiator`
-    method.
-
-    For example:
-
-    .. code-block:: python
-       :linenos:
+.. code-block:: python
+   :linenos:
 
-       from pyramid.configuration import Configurator
-       config = Configurator()
-       config.begin()
-       config.set_locale_negotiator(my_locale_negotiator)
-       config.end()
+   from pyramid.configuration import Configurator
+   config = Configurator(locale_negotiator=my_locale_negotiator)
 
-.. topic:: Using ZCML
+Alternately, use the
+:meth:`pyramid.configuration.Configurator.set_locale_negotiator`
+method.
 
-    You can add a locale negotiator via ZCML by using the
-    :ref:`localenegotiator_directive` ZCML directive:
+For example:
 
-    .. code-block:: xml
-       :linenos:
+.. code-block:: python
+   :linenos:
 
-       <localenegotiator 
-        negotiator="my_application.my_module.my_locale_negotiator"/>
+   from pyramid.configuration import Configurator
+   config = Configurator()
+   config.begin()
+   config.set_locale_negotiator(my_locale_negotiator)
+   config.end()
 
+.. note:: You can also add a custom locale negotiator via ZCML.  See
+   :ref:`zcml_adding_a_locale_negotiator`