Translations

Provide multilingual support for your plugin's user interface.

Translation Files

Create translation files in Resources/translations/ or translations/:

plugins/my-plugin/
└── Resources/
    └── translations/
        ├── messages.en.yaml
        ├── messages.pl.yaml
        └── messages.de.yaml

Translation Domain

Use plugin_{plugin_name} as the translation domain (snake_case!):

• plugin_my_plugin

• plugin_hello_world

• plugin_paypal_payment

English Translations (messages.en.yaml)

page:
    title: 'My Plugin Dashboard'
    subtitle: 'Manage your plugin settings'

nav:
    menu_item: 'My Plugin'

widget:
    my_widget:
        title: 'Widget Title'
        no_data: 'No data available'
        last_updated: 'Last updated'

form:
    label:
        api_key: 'API Key'
        api_endpoint: 'API Endpoint'
        enabled: 'Enabled'
    help:
        api_key: 'Enter your API key from the provider'

button:
    save: 'Save Settings'
    cancel: 'Cancel'
    delete: 'Delete'
    confirm: 'Confirm'

message:
    success:
        saved: 'Settings saved successfully'
        deleted: 'Item deleted'
    error:
        save_failed: 'Failed to save settings'
        invalid_input: 'Invalid input provided'

Polish Translations (messages.pl.yaml)

page:
    title: 'Panel wtyczki'
    subtitle: 'Zarządzaj ustawieniami wtyczki'

nav:
    menu_item: 'Moja wtyczka'

widget:
    my_widget:
        title: 'Tytuł widżetu'
        no_data: 'Brak danych'
        last_updated: 'Ostatnia aktualizacja'

form:
    label:
        api_key: 'Klucz API'
        api_endpoint: 'Punkt końcowy API'
        enabled: 'Włączone'
    help:
        api_key: 'Wprowadź klucz API od dostawcy'

button:
    save: 'Zapisz ustawienia'
    cancel: 'Anuluj'
    delete: 'Usuń'
    confirm: 'Potwierdź'

message:
    success:
        saved: 'Ustawienia zapisane pomyślnie'
        deleted: 'Element usunięty'
    error:
        save_failed: 'Nie udało się zapisać ustawień'
        invalid_input: 'Podano nieprawidłowe dane'

Using Translations in Templates

{# Simple translation #}
{{ 'page.title'|trans({}, 'plugin_my_plugin') }}

{# Translation with parameters #}
{{ 'message.greeting'|trans({'%name%': user.name}, 'plugin_my_plugin') }}

{# Translation with count (pluralization) #}
{{ 'item.count'|trans({'%count%': items|length}, 'plugin_my_plugin') }}

Using Translations in PHP

use Symfony\Contracts\Translation\TranslatorInterface;

class MyController extends AbstractController
{
    public function __construct(
        private readonly TranslatorInterface $translator,
    ) {}

    public function index(): Response
    {
        $message = $this->translator->trans(
            'message.success.saved',
            [],
            'plugin_my_plugin'
        );

        $this->addFlash('success', $message);

        return $this->render('@PluginMyPlugin/index.html.twig');
    }
}

Parameterized Translations

# messages.en.yaml
message:
    greeting: 'Hello, %name%!'
    items_found: 'Found %count% items'
    user_registered: '%username% registered on %date%'

{# In Twig template #}
{{ 'message.greeting'|trans({'%name%': 'John'}, 'plugin_my_plugin') }}
{# Output: Hello, John! #}

{{ 'message.items_found'|trans({'%count%': 42}, 'plugin_my_plugin') }}
{# Output: Found 42 items #}

// In PHP
$this->translator->trans('message.user_registered', [
    '%username%' => $user->getName(),
    '%date%' => $registrationDate->format('Y-m-d')
], 'plugin_my_plugin');
// Output: John registered on 2025-12-16

Pluralization

# messages.en.yaml
item:
    count: '{0} No items|{1} One item|]1,Inf[ %count% items'

{{ 'item.count'|trans({'%count%': 0}, 'plugin_my_plugin') }}
{# Output: No items #}

{{ 'item.count'|trans({'%count%': 1}, 'plugin_my_plugin') }}
{# Output: One item #}

{{ 'item.count'|trans({'%count%': 5}, 'plugin_my_plugin') }}
{# Output: 5 items #}

Translation Keys Organization

Organize keys by component/section:

# Navigation
nav:
    main_menu: 'Dashboard'
    settings: 'Settings'
    logout: 'Logout'

# Widgets
widget:
    balance:
        title: 'Account Balance'
        current: 'Current Balance'
    servers:
        title: 'My Servers'
        count: 'Server Count'

# Forms
form:
    label:
        email: 'Email Address'
        password: 'Password'
    placeholder:
        email: '[email protected]'
    help:
        password: 'Min. 8 characters'

# Buttons
button:
    save: 'Save'
    cancel: 'Cancel'
    submit: 'Submit'
    back: 'Back'

# Flash messages
flash:
    success: 'Operation completed successfully'
    error: 'An error occurred'
    warning: 'Please check your input'

# Validation errors
validation:
    required: 'This field is required'
    email: 'Please enter a valid email'
    min_length: 'Minimum length is %min% characters'

Language Detection

PteroCA automatically detects user language based on:

1. User's selected language (from profile)

2. Browser's Accept-Language header

3. System default language

Translation Best Practices

1. Use clear key structure - organize by section/component

2. Provide all translations - at minimum English

3. Use parameters for dynamic content

4. Keep translations short - especially for buttons/labels

5. Test with different languages - ensure UI layout works

6. Document translation keys - for other translators

7. Use consistent terminology - same words for same concepts

8. Avoid hardcoded text - always use translation keys

Translation File Locations

Two locations are supported:

Option 1: Resources/translations/

plugins/my-plugin/
└── Resources/
    └── translations/
        └── messages.en.yaml

Option 2: translations/

plugins/my-plugin/
└── translations/
    └── plugin_my_plugin.en.yaml

Choose one location and be consistent.

Translation Testing

Test translations by changing language:

# Set user language in database
docker exec pteroca_web_dev php bin/console pteroca:user:set-language [email protected] pl

# Clear cache after translation changes
docker exec pteroca_web_dev php bin/console cache:clear

Related Guides

• UI Components - Translate widgets and tabs

• Controllers & Routes - Flash messages

• CRUD Controllers - Admin interface translations