Merge branch '2.7' into 2.8

* 2.7:
  Added minor clarification about what StudlyCaps is
  Update best_practices.rst
  Removed the reference to specific Symfony files
  Added a new section "Extracting Translation Contents and Updating Cat…
  Moved the note before the label
  Minor reword
  moved the tips to an include fragment file
  added a tip to register annotations namespaces

Author: javiereguiluz

_includes/_annotation_loader_tip.rst.inc

@@ -0,0 +1,19 @@
+.. note::
+
+    In order to use the annotation loader, you should have installed the
+    ``doctrine/annotations`` and ``doctrine/cache`` packages with Composer.
+
+.. tip::
+
+    Annotation classes aren't loaded automatically, so you must load them
+    using a class loader like this::
+
+        use Composer\Autoload\ClassLoader;
+        use Doctrine\Common\Annotations\AnnotationRegistry;
+
+        /** @var ClassLoader $loader */
+        $loader = require __DIR__.'/../vendor/autoload.php';
+
+        AnnotationRegistry::registerLoader([$loader, 'loadClass']);
+
+        return $loader;

bundles/best_practices.rst

@@ -37,7 +37,7 @@ A namespace becomes a bundle as soon as you add a bundle class to it. The
 bundle class name must follow these simple rules:
 
 * Use only alphanumeric characters and underscores;
-* Use a CamelCased name;
+* Use a StudlyCaps name (i.e. camelCase with the first letter uppercased);
 * Use a descriptive and short name (no more than two words);
 * Prefix the name with the concatenation of the vendor (and optionally the
   category namespaces);

components/routing.rst

@@ -312,6 +312,8 @@ Last but not least there are
 route definitions from class annotations. The specific details are left
 out here.
 
+.. include:: /_includes/_rewrite_rule_tip.rst.inc
+
 The all-in-one Router
 ~~~~~~~~~~~~~~~~~~~~~
 

components/serializer.rst

@@ -310,6 +310,8 @@ You are now able to serialize only attributes in the groups you want::
     );
     // $obj2 = MyObj(foo: 'foo', bar: 'bar')
 
+.. include:: /_includes/_rewrite_rule_tip.rst.inc
+
 .. _ignoring-attributes-when-serializing:
 
 Ignoring Attributes

components/validator/resources.rst

@@ -119,10 +119,7 @@ method. It takes an optional annotation reader instance, which defaults to
 To disable the annotation loader after it was enabled, call
 :method:`Symfony\\Component\\Validator\\ValidatorBuilder::disableAnnotationMapping`.
 
-.. note::
-
-    In order to use the annotation loader, you should have installed the
-    ``doctrine/annotations`` and ``doctrine/cache`` packages from `Packagist`_.
+.. include:: /_includes/_rewrite_rule_tip.rst.inc
 
 Using Multiple Loaders
 ----------------------

translation.rst

@@ -107,13 +107,12 @@ of text (called a *message*), use the
 for example, that you're translating a simple message from inside a controller::
 
     // ...
-    use Symfony\Component\HttpFoundation\Response;
 
     public function indexAction()
     {
         $translated = $this->get('translator')->trans('Symfony is great');
 
-        return new Response($translated);
+        // ...
     }
 
 .. _translation-resources:
@@ -185,13 +184,11 @@ Message Placeholders
 
 Sometimes, a message containing a variable needs to be translated::
 
-    use Symfony\Component\HttpFoundation\Response;
-
     public function indexAction($name)
     {
         $translated = $this->get('translator')->trans('Hello '.$name);
 
-        return new Response($translated);
+        // ...
     }
 
 However, creating a translation for this string is impossible since the translator
@@ -258,11 +255,11 @@ You can also specify the message domain and pass some additional variables:
 
 .. code-block:: twig
 
-    {% trans with {'%name%': 'Fabien'} from "app" %}Hello %name%{% endtrans %}
+    {% trans with {'%name%': 'Fabien'} from 'app' %}Hello %name%{% endtrans %}
 
-    {% trans with {'%name%': 'Fabien'} from "app" into "fr" %}Hello %name%{% endtrans %}
+    {% trans with {'%name%': 'Fabien'} from 'app' into 'fr' %}Hello %name%{% endtrans %}
 
-    {% transchoice count with {'%name%': 'Fabien'} from "app" %}
+    {% transchoice count with {'%name%': 'Fabien'} from 'app' %}
         {0} %name%, there are no apples|{1} %name%, there is one apple|]1,Inf[ %name%, there are %count% apples
     {% endtranschoice %}
 
@@ -277,7 +274,7 @@ texts* and complex expressions:
 
     {{ message|transchoice(5) }}
 
-    {{ message|trans({'%name%': 'Fabien'}, "app") }}
+    {{ message|trans({'%name%': 'Fabien'}, 'app') }}
 
     {{ message|transchoice(5, {'%name%': 'Fabien'}, 'app') }}
 
@@ -308,7 +305,7 @@ texts* and complex expressions:
 
     .. code-block:: twig
 
-           {% trans_default_domain "app" %}
+           {% trans_default_domain 'app' %}
 
     Note that this only influences the current template, not any "included"
     template (in order to avoid side effects).
@@ -329,6 +326,33 @@ The translator service is accessible in PHP templates through the
         array('%count%' => 10)
     ) ?>
 
+Extracting Translation Contents and Updating Catalogs Automatically
+-------------------------------------------------------------------
+
+The most time-consuming tasks when translating an application is to extract all
+the template contents to be translated and to keep all the translation files in
+sync. Symfony includes a command called ``translation:update`` that helps you
+with these tasks:
+
+.. code-block:: terminal
+
+    # updates the French translation file with the missing strings found in app/Resources/ templates
+    $ ./app/console translation:update --dump-messages --force fr
+
+    # updates the English translation file with the missing strings found in AppBundle
+    $ ./app/console translation:update --dump-messages --force en AppBundle
+
+.. note::
+
+    If you want to see the missing translation strings without actually updating
+    the translation files, remove the ``--force`` option from the command above.
+
+.. tip::
+
+    If you need to extract translation strings from other sources, such as
+    controllers, forms and flash messages, consider using the more advanced
+    third-party `TranslationBundle`_.
+
 .. _translation-resource-locations:
 
 Translation Resource/File Names and Locations
@@ -513,3 +537,4 @@ Learn more
 .. _`ISO 639-1`: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
 .. _`Translatable Extension`: http://atlantic18.github.io/DoctrineExtensions/doc/translatable.html
 .. _`Translatable Behavior`: https://github.com/KnpLabs/DoctrineBehaviors
+.. _`TranslationBundle`: https://github.com/php-translation/symfony-bundle