README

Description:

This bundle provides a nice way of generating translation keys for form fields in a "logic" way. It is used mainly to generate automatic labels on fields but can be use to build any key.

For example, in a form RegisterType named "register" the key for its field "name" would be form.register.children.name.label.

Another more advanced example would be a field "emails" which is a collection of text inputs, it'll generate:

• form.register.children.emails.label
• form.register.children.emails.label_add
• form.register.children.emails.label_delete
• form.register.children.emails.children.prototype.label

Or in yml:

form:
    register:
        children:
            emails:
                label:          # add your trans for the fieldset ex: Email
                label_add:      # add your trans for add button ex: Add an email
                label_delete:   # add your trans for remove button ex: Remove an email
                children:
                    prototype:
                        label:  # add your trans for the label of one email field ex: Email address

Note: The keys will only be generated at runtime and won't be dumped when you use translation:update yet (we're working on it).

Installation:

Add ElaoFormTranslationBundle to your composer.json:

{
    "require": {
        "elao/form-translation-bundle": "3.*"
    }
}

Now download the bundle by running the command:

$ php composer.phar update elao/form-translation-bundle

Register the bundle in the kernel:

<?php
// app/AppKernel.php

public function registerBundles()
{
    $bundles = array(
        // ...
        new Elao\Bundle\FormTranslationBundle\ElaoFormTranslationBundle(),
    );
}

How to use it:

In order to generate translation keys automatically, you have 2 options:

Per field generation:

If you set the the "label" option of a form field to true, a key will be generated and set as the field label. Otherwise we won't generate your labels !

<?php

class RegisterType extends AbstractType
{
    /**
     * {@inheritdoc}
     */
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder
            ->add('name', null, array(
                'label' => true // Will generate: "form.register.children.name.label"
            ));
            ->add('email', null, array(
                'label' => false // Will NOT generate a `<label>` in the `HTML`
            ));
            ->add('email', null, array(
                'label' => 'my.custom.key' // Default behavior
            ));
    }

    /**
     * {@inheritdoc}
     */
    public function getName()
    {
        return 'register';
    }
}

Global configuration key:

If you want to generate keys for all your labels you can set the option auto_generate to true:

elao_form_translation:
    auto_generate: true

This will set default label value to true so keys will be generated for every label.

If you need to override this behavior, you can still provide a label key for your field in order to use your translation key. In this case, no keys will be generated.

Customization and configuration:

Customize the keys:

Keys are built following this pattern:

[root][separator](parent_field_name)[separator][children][separator](field_name)[key]

You can customize (and remove) any of these tokens to change the way keys are built:

elao_form_translation:
    blocks:
        # Prefix for children nodes (string|false)
        children:   "children"

        # Prefix for prototype nodes (string|false)
        prototype:  "prototype"

        # Prefix at the root of the key (string|false)
        root:       "form"

        # Separator te be used between nodes (string|false)
        separator:  "."

For example, if you just need simple keys you could do with the following configuration:

elao_form_translation:
    blocks:
        root:      false
        children:  false
        separator: "_"

Which would generate that kind of keys:

# (parent_field_name)[separator](field_name)[separator][key]
register_name_label

Set default translation domain for all forms

You can set a default translation domain for all forms and choice with the following configuration:

elao_form_translation:
    default_translation_domain: "forms"

This will set the default options translation_domain and choice_translation_domain to all forms and choices off your application.

You still can override these options in each configureOptions method of your form types.

You can also disable translation on all form by setting the option to false:

elao_form_translation:
    default_translation_domain: false

Default configuration:

elao_form_translation:

    # Can be disabled
    enabled: true

    # Generate translation keys for all missing labels
    auto_generate: false

    # Set default translation domain on all forms
    default_translation_domain: ~

    # Customize available keys
    keys:
        form:
            label:  "label"
            help:   "help"
            # Add yours ...
        collection:
            label_add:      "label_add"
            label_delete:   "label_delete"
            # Add yours ...

    # Customize the ways keys are built
    blocks:

        # Prefix for prototype nodes
        prototype:  "prototype"

        # Prefix for children nodes
        children:   "children"

        # Prefix at the root of the key
        root:       "form"

        # Separator te be used between nodes
        separator:  "."