Improve translation of labels (and docs)

Resources/doc/tutorials/i18n.md

@@ -28,52 +28,110 @@ The backend interface uses the same language as the underlying Symfony
 application. If you want to change it, update the value of the `locale` option
 in the `app/config/parameters.yml` file.
 
-If you want to change any of the built-in translations defined under the
-`EasyAdminBundle` domain, use the [translation override mechanism](http://symfony.com/doc/current/cookbook/bundles/override.html#translations)
-provided by Symfony.
-
 EasyAdmin is already translated into tens of languages thanks to the generosity
 of its community. We're actively looking for more translations, so please
 consider contributing a translation for your own language.
 
+> **NOTE**
+>
+> Although it's not recommended to do it, if you want to change any of the
+> built-in translations defined under the `EasyAdminBundle` domain, use the
+> [translation override mechanism](http://symfony.com/doc/current/cookbook/bundles/override.html#translations)
+> provided by Symfony.
+
 Translate the Main Menu Labels
 ------------------------------
 
-The main menu labels are defined in the `label` configuration option of each
-entity. In order to translate these labels, use translation keys instead of their
-real contents in the configuration file:
+Menu items use the **entity name** as their label. The entity name is the YAML
+key used to define the configuration of each entity. For example, the following
+configuration would show two menu items called `Customers` and `Orders`:
+
+```yaml
+# app/config/config.yml
+easy_admin:
+    entities:
+        Customers:
+            class: AppBundle\Entity\User
+        Orders:
+            class: AppBundle\Entity\Purchase
+```
+
+The `messages.xx.yml` (or `messages.xx.xlf`) file for the previous example would
+need to use `Customers` and `Orders` as the keys of the translations. Example:
+
+```yaml
+# app/Resources/translations/messages.es.yml
+Customers: Clientes
+Orders: Ventas
+```
+
+Main menu labels can be customized thanks to the `label` option of each entity.
+You can even use structured translation keys instead of the real contents:
 
 ```yaml
 # app/config/config.yml
 easy_admin:
     entities:
         Customers:
             label: app.menu.customers
-            class: AppBundle\Entity\Customer
+            class: AppBundle\Entity\User
         Orders:
             label: app.menu.orders
-            class: AppBundle\Entity\Order
+            class: AppBundle\Entity\Purchase
 ```
 
-If your application contains a translation file which defines the value of those
-keys for the active language, you'll see the main menu labels translated.
-Otherwise you'll see `app.menu.customers` and `app.menu.orders` as the menu labels.
+In this case, the translation file should use the value of the `label` option as
+the keys of the translations (and you should also create the file for the
+original language used by the translation keys):
+
+```yaml
+# app/Resources/translations/messages.en.yml
+app.menu.customers: Customers
+app.menu.orders: Orders
+
+# app/Resources/translations/messages.es.yml
+app.menu.customers: Clientes
+app.menu.orders: Ventas
+```
 
 Translate Property Labels
 -------------------------
 
-By default, the label of each property is the "humanized" version of its name
-(e.g. `propertyname` -> `Propertyname`; `propertyName` -> `Property name`;
-`property_name` -> `Property name`). Before rendering the labels, their contents
-are also translated.
+The behavior of the property labels is very similar to the one explained in the
+previous section for the main menu. By default, the label of each property is
+the "humanized" version of its name:
 
-Therefore, if you define the translation of these "humanized" property names
-anywhere in your application, these translations will be automatically used by
-the backend.
+| Property value  | Default property label
+| --------------- | ----------------------
+| `propertyname`  | `Propertyname`
+| `propertyName`  | `Property name`
+| `property_name` | `Property name`
+
+Consider the following configuration:
+
+```yaml
+# app/config/config.yml
+easy_admin:
+    entities:
+        Customer:
+            class: AppBundle\Entity\Customer
+            list:
+                fields: ['firstName', 'lastName']
+        # ...
+```
+
+The backend will display `First name` and `Last name` as the labels of the
+properties, so those are the translation keys that must be used:
+
+```yaml
+# app/Resources/translations/messages.es.yml
+First name: Nombre
+Last name: Apellidos
+```
 
 Alternatively, you can use the `label` option of each property to define its
-label explicitly. The trick to make the labels translatable is to put the
-translation key as the content of the `label` option:
+label explicitly. You can even use structured translation keys instead of the
+real contents:
 
 ```yaml
 # app/config/config.yml
@@ -88,6 +146,16 @@ easy_admin:
         # ...
 ```
 
-If your application contains a translation file which defines the value of those
-keys for the active language, you'll see these labels translated. Otherwise
-you'll see `app.users.firstName` and `app.users.lastName` as the labels.
+In this case, the translation file should use the value of the `label` option as
+the keys of the translations (and you should also create the file for the
+original language used by the translation keys):
+
+```yaml
+# app/Resources/translations/messages.en.yml
+app.menu.firstName: First name
+app.menu.lastName: Last name
+
+# app/Resources/translations/messages.es.yml
+app.menu.firstName: Nombre
+app.menu.lastName: Apellidos
+```

Resources/views/default/list.html.twig

@@ -83,7 +83,7 @@
                 {% for field, metadata in fields %}
                     {% set isSortingField = metadata.property == app.request.get('sortField') %}
                     {% set nextSortDirection = isSortingField ? (app.request.get('sortDirection') == 'DESC' ? 'ASC' : 'DESC') : 'DESC' %}
-                    {% set _column_label = metadata.label ? metadata.label|trans(_trans_parameters) : field|humanize %}
+                    {% set _column_label = (metadata.label ?: field|humanize)|trans(_trans_parameters) %}
                     {% set _column_icon = isSortingField ? (nextSortDirection == 'DESC' ? 'fa-caret-up' : 'fa-caret-down') : 'fa-sort' %}
 
                     <th data-property-name="{{ metadata.property }}" class="{{ isSortingField ? 'sorted' }} {{ metadata.virtual ? 'virtual' }} {{ metadata.dataType|lower }}">
@@ -114,7 +114,7 @@
                 <tr data-id="{{ _item_id }}">
                     {% for field, metadata in fields %}
                         {% set isSortingField = metadata.property == app.request.get('sortField') %}
-                        {% set _column_label =  metadata.label ? metadata.label|trans(_trans_parameters) : field|humanize %}
+                        {% set _column_label =  (metadata.label ?: field|humanize)|trans(_trans_parameters)  %}
 
                         <td data-label="{{ _column_label }}" class="{{ isSortingField ? 'sorted' }} {{ metadata.dataType|lower }}">
                             {{ easyadmin_render_field_for_list_view(_entity_config.name, item, metadata) }}