Developed with love by KnpLabs Hire us for your project!
62

ElaoFormTranslationBundle

by Elao

Provides a nice way of generating translation keys for form fields

ElaoFormTranslationBundle


Build Status

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:
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:  "."

# <info>Activate the Form Tree component (used to generate label translation keys)</info>
elao_form_translation:
enabled: true

# <info>Generate translation keys for all missing keys</info>
auto_generate: false

# <info>Customize available keys</info>
keys:
form:

# Defaults:
label: label
help: help
collection:

# Defaults:
label_add: label_add
label_delete: label_delete
choice:

# Default:
empty_value: empty_value

# <info>Customize the ways keys are built</info>
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: .

# <info>Default translation domain for all forms</info>
default_translation_domain: ~
  • Merge pull request #34 from Elao/symfony5.x
    By web-flow, 7 months ago
  • Improve tooling
    By maximecolin, 7 months ago
  • Add PHP 8 and Symfony 5.2 to travis config
    By maximecolin, 7 months ago
  • Drop PHP 7.0 support
    By maximecolin, 7 months ago
  • Symfony 5.0 compatibility
    By maximecolin, 7 months ago
  • Merge pull request #33 from Elao/null-default-translation-domain
    By web-flow, 2 years ago
  • Set null as default translation domain
    By maximecolin, 2 years ago
  • Merge pull request #32 from Elao/help-boolean
    By web-flow, 2 years ago
  • Allow help option to be a boolean
    By maximecolin, 2 years ago
  • Merge pull request #31 from Elao/fix/composer-branch-alias
    By web-flow, 2 years ago
  • Fix composer branch alias for v3
    By web-flow, 2 years ago
  • Merge pull request #30 from Elao/NicolasDievart-patch-1
    By web-flow, 2 years ago
  • Update version in Readme
    By web-flow, 2 years ago
  • Merge pull request #29 from Elao/default-translation-domain
    By web-flow, 2 years ago
  • Merge pull request #28 from Elao/fix-deprecated
    By web-flow, 2 years ago
  • Update readme
    By maximecolin, 2 years ago
  • Allow to set translation domain for all forms
    By maximecolin, 2 years ago
  • Drop php 5.6
    By maximecolin, 2 years ago
  • Fix deprecated
    By maximecolin, 2 years ago
  • Merge pull request #27 from Elao/update-to-symfony-4
    By web-flow, 2 years ago
  • Remove strict addition on in_array
    By NicolasDievart, 2 years ago
  • Update badge
    By NicolasDievart, 2 years ago
  • Update README version of bundle
    By NicolasDievart, 2 years ago
  • Update phpunit to version 5 and drop travis test on php5.5
    By NicolasDievart, 2 years ago
  • Downgrade phpunit to stay php 5.5 compliant
    By NicolasDievart, 2 years ago
  • Update to allow Symfony 4 and fix CS
    By NicolasDievart, 2 years ago
  • Fix branch alias
    By benji07, 5 years ago
  • Merge pull request #21 from Elao/symfony3
    By Tom32i, 5 years ago
  • Added symfony badge
    By Tom32i, 5 years ago
  • Fixed phpunit path
    By Tom32i, 5 years ago