Merge pull request #1698 from plone/erral-overriding-translations

explain how to avoid errors when overriding translations

Author: stevepiercy

docs/i18n-l10n/translating-text-strings.md

@@ -437,6 +437,29 @@ environment-vars =
 zcml = my.package
 ```
 
+When doing so, you may need to add the following ZCML stanza in your package's {file}`configure.zcml` file:
+
+```xml
+<include package="Products.CMFPlone" />
+```
+
+This **must** go *after* the `registerTranslations` stanza, and before any other registration you might have in your package.
+
+The registration should look like the following example.
+
+```xml
+<configure xmlns:i18n="http://namespaces.zope.org/i18n"
+           i18n_domain="my.package">
+    <i18n:registerTranslations directory="locales" />
+    
+    <include package="Products.CMFPlone" />
+
+    <!-- any other registration -->
+
+</configure>
+```
+
+
 See the *Overriding Translations* section of Maurits van Rees's [blog entry on Plone i18n](https://maurits.vanrees.org/weblog/archive/2010/10/i18n-plone-4#overriding-translations).