From 2af497a5a59296df7f90de8c59019a66454f1eb1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gr=C3=A9goire=20Paris?= <postmaster@greg0ire.fr>
Date: Sat, 3 Oct 2015 15:39:40 +0200
Subject: [PATCH] Document the label translator strategy feature

---
 Resources/doc/index.rst                       |  1 +
 .../reference/label_translator_strategy.rst   | 39 +++++++++++++++++++
 2 files changed, 40 insertions(+)
 create mode 100644 Resources/doc/reference/label_translator_strategy.rst

diff --git a/Resources/doc/index.rst b/Resources/doc/index.rst
index da907f522a7..eb2e4773d22 100644
--- a/Resources/doc/index.rst
+++ b/Resources/doc/index.rst
@@ -32,6 +32,7 @@ Reference Guide
    reference/action_delete
    reference/action_export
    reference/saving_hooks
+   reference/label_translator_strategy
    reference/form_types
    reference/form_help_message
    reference/field_types
diff --git a/Resources/doc/reference/label_translator_strategy.rst b/Resources/doc/reference/label_translator_strategy.rst
new file mode 100644
index 00000000000..d650c4d0fdf
--- /dev/null
+++ b/Resources/doc/reference/label_translator_strategy.rst
@@ -0,0 +1,39 @@
+Label translator strategy
+=========================
+
+A label translator strategy processes labels so that they can follow a given
+naming policy. It implements
+``Sonata\AdminBundle\Translator\LabelTranslatorStrategyInterface``, which
+consists of one method, with the following signature :
+``public function getLabel($label, $context = '', $type = '');``. In the context
+of a form with an ``isValid`` field, it is called as follows :
+``$strategy->getLabel('isValid', 'form', 'label')``
+
+Several built-in label translator strategies are available.
+
+``sonata.admin.label.strategy.bc``
+    Backwards-Compatible label translator strategy. Labels are as they where
+    before label translator strategies where introduced. The above call will
+    produce ``Isvalid``. Avoid it if you are creating a new project.
+
+``sonata.admin.label.strategy.native``
+    This is the default. It tries to humanize the given label. The above call
+    will produce ``Is Valid``.
+
+``sonata.admin.label.strategy.noop``
+    You guessed it, this one does nothing.
+
+``sonata.admin.label.strategy.underscore``
+    This is the strategy you should use if you use Symfony's i18n features. The
+    above call will produce ``form.label_is_valid``. When testing your admin,
+    looking for ``form.label`` in the page is an easy way to catch missing
+    translations. If you have a recent version of Symfony (2.6) you can also
+    check the missing translation logger in your tests.
+
+``sonata.admin.label.strategy.form_component``
+    Not sure why the name, feel free to change this sentence if you know. This
+    strategy puts everything in lowercase, then capitalizes the first letter.
+    The above call will produce ``Isvalid``.
+
+If you cannot find a strategy that fits your use case, you can easily implement
+and use your own. If you do, consider contributing your strategy.