LexikTranslationBundle Documentation

To install the bundle, add it to your composer.json and register it in your application kernel. After installation, you must install the required assets and, if using Doctrine ORM, update your database schema.

1. Add to composer.json:

   "require": {
       "lexik/translation-bundle": "~7.1"
   }

2. Install via CLI:

   composer require lexik/translation-bundle ~7.1

3. Register the bundle in your AppKernel.php:

   new Lexik\Bundle\TranslationBundle\LexikTranslationBundle(),

4. Install assets:

   ./bin/console assets:install

5. Update Doctrine schema (if using ORM):

   ./bin/console doctrine:schema:update --force

If you are using the provided Docker setup, you can manage the test lifecycle using docker-compose. This ensures the environment is consistent with the project requirements.

# Run the full test suite
docker-compose run --rm lexik_translation composer test

# Build the image without cache
docker-compose build --no-cache

# Run a specific test file with a filter
docker-compose run --rm lexik_translation composer test Tests/Unit/Translation/Manager/TransUnitManagerTest.php --filter testORMAddTranslation

If make is unavailable (e.g., on Windows), you can perform all development tasks by running commands directly via Docker Compose. All commands target the lexik_translation service to ensure the correct PHP environment is used.

# 1. Start services and install dependencies
docker compose up -d
docker compose run --rm lexik_translation composer install --prefer-dist --no-progress

# 2. Run tests
docker compose run --rm lexik_translation composer test

# 3. Run PHPStan
docker compose run --rm lexik_translation vendor/bin/phpstan analyse --memory-limit=512M

# 4. Run PHP-CS-Fixer
docker compose run --rm lexik_translation vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.dist.php

# 5. Run Rector
docker compose run --rm lexik_translation vendor/bin/rector process

On Linux or macOS, you can use the project's Makefile to manage development tooling. All PHP commands are executed inside the lexik_translation Docker container, meaning you do not need PHP or specific extensions installed on your host machine. Ensure GNU Make is installed.

make help        # List all available commands
make ensure-up   # Start Docker services and install Composer dependencies
make test        # Run PHPUnit
make phpstan     # Run PHPStan
make cs-fix      # Run PHP-CS-Fixer
make rector      # Run Rector
make install     # Composer install
make update      # Composer update
make cache-clear # Clear Composer cache
make up          # Start containers only
make down        # Stop containers
make build       # Build Docker images

You can run the test suite directly using the phpunit.phar executable. If your environment requires specific database credentials for the Doctrine PDO driver, you can export them as environment variables before running the command.

$ phpunit.phar

To access the translation edition interface (Overview and Grid), add the bundle's routing configuration to your application.

# app/config/routing.yml
lexik_translation_edition:
    resource: "@LexikTranslationBundle/Resources/config/routing.yml"
    prefix: /my-prefix

Endpoints:

• /my-prefix/ : Overview page
• /my-prefix/grid : Translations grid

Note: If the grid does not appear, ensure your base template contains a block named javascript_footer.

You can specify where translations are stored (ORM or MongoDB) and how they are loaded.

Storage Configuration

By default, the bundle uses Doctrine ORM. You can switch to MongoDB (requires MongoDB 2.0.0+) and specify a custom object_manager name.

lexik_translation:
    storage:
        type: orm                  # orm | mongodb
        object_manager: something  # Name of the entity/document manager

Resource Loading

Define whether to load translations from files, the database, or both. If both are used, database values override file values.

lexik_translation:
    resources_registration:
        type:                 all  # all | files | database
        managed_locales_only: true

Customize the appearance and behavior of the translation grid and the export process.

Exporter Options

• use_yml_tree: Set to true to print a nice tree in YAML files (slower).
• json_hierarchical_format: Set to true for hierarchical JSON structure.

lexik_translation:
    exporter:
        use_yml_tree: false
        json_hierarchical_format: false

Grid UI Options

• base_layout: The Twig template used for the bundle. Use @LexikTranslation/layout.html.twig for modern Symfony/Twig versions.
• grid_input_type: text or textarea.
• grid_toggle_similar: If true, toggling a locale column (e.g., en) also toggles similar locales (e.g., en_XX).

lexik_translation:
    base_layout: "@LexikTranslation/layout.html.twig"
    grid_input_type: text
    grid_toggle_similar: false

Automatic Cache Cleaning

Enable the bundle to automatically clear translation cache files based on the latest update date in the database.

lexik_translation:
    auto_cache_clean: false
    auto_cache_clean_interval: 600 # seconds

Development Tools

In dev environments, you can enable tools to find untranslated keys. If create_missing is enabled, the bundle will create missing key/domain pairs in the database and associate them with files in app/Resources/translations.

lexik_translation:
    dev_tools:
        enable: false
        create_missing: false
        file_format: yml

The bundle decorates the Symfony Translator service. It is recommended to use standard Symfony framework configuration for locales and fallbacks.

Minimal Setup (Recommended)

Use the standard Symfony framework configuration. The bundle will automatically use enabled_locales and translator.fallbacks.

# config/packages/framework.yaml
framework:
    default_locale: en
    enabled_locales: [en, fr, de]
    translator:
        fallbacks: [en]

Legacy Setup

You can still use lexik_translation options for backward compatibility, but they will override framework values. Note that fallback_locale is deprecated.

# config/packages/lexik_translation.yaml
lexik_translation:
    fallback_locale: [en]         # Deprecated
    managed_locales: [en, fr, de] # Optional