Download the PHP package drago-ex/translator without Composer

Drago Translator

Lightweight translator for Nette Framework using NEON files. Translation directories can be declared automatically in Composer packages and in the root application, with an optional manual NEON configuration for special cases.

Requirements

• PHP >= 8.3, < 9
• Nette Framework
• Composer 2.1+

Installation

Extension Registration

Register the DI extension in your NEON configuration:

No translation directories are required in NEON for the normal case. The translator discovers them from Composer metadata.

Composer Translation Discovery

Each Composer package can declare one directory containing its translation files in composer.json:

The path is relative to the root of that Composer package. If the directory is not there (for example because the package resources were copied into the application), the same path is looked up in the project root.

For example, a package installed as:

with:

provides translations from:

The package does not need to depend on drago-ex/translator. The metadata is simply available for applications that use this translator. Other translation systems can ignore it.

Root application

The root composer.json can declare the application's translation directory in exactly the same way:

The path is then resolved relative to the project root.

This makes the setup automatic after installing a package. The application does not need to add a new NEON entry for every vendor package.

Translation precedence

Translation sources are loaded in this order:

1. Composer vendor packages.
2. The root application's Composer translation directory.
3. Translation directories configured manually in NEON.

Later sources override translations loaded earlier. This means an application can override a translation supplied by a vendor package.

For example, if both a package and the application define:

the application's value wins.

Manual translation directories

Composer discovery is the recommended approach, but a manual fallback is available for special cases:

Multiple directories are supported when needed:

They are loaded after Composer-discovered translations, in the configured order. Later directories override earlier ones.

There is no automatic recursive scan of the whole application directory. Every translation source must therefore be explicitly declared either in Composer metadata or in translateDirs.

Translation Files

Translation files must use the language code as their filename, for example:

Files like cs-CZ.neon are loaded too when cs is requested. The base file cs.neon is loaded first, the others follow alphabetically. The language code must look like cs or cs-CZ; anything else finds no files.

Translation File Format

Values must be strings; anything else (nested arrays, booleans) is ignored.

Parameters in Translations

Translations can contain sprintf-style placeholders. Pass their values after the message key; the translator inserts them in order using PHP's vsprintf():

The same works with the translator registered in Latte:

Use a matching placeholder for each argument, in the same order. Common placeholders include %s for text, %d for an integer, and %.2f for a decimal number with two digits after the decimal point.

When no translation exists, the original message is used and its placeholders are formatted in the same way. If the placeholders do not match the arguments, the unformatted text is returned instead of throwing.

Tracy Panel

In debug mode the Tracy bar shows the current language, manually configured directories, loaded files and the messages that had no translation. Messages are reported only when the language has at least one translation file loaded, so a source-language file is not needed.

Using Translator in Presenters

Add the TranslatorAdapter trait to your presenter:

The trait provides:

• persistent language parameter ($lang)
• automatic translator initialization
• template integration

Accessing the Current Language

You can access the currently set language using:

Getting Translator Instance

To get the initialized translator for the current language:

Using Translations in Templates

The translator is automatically registered in templates.

Using Translator in Forms

To enable translations in forms, set the translator explicitly:

Routing for Language Switching

To support language prefixes, configure your routes accordingly:

Switching Languages in Templates

You can switch languages by passing the lang parameter:

Language Switch Widget

The package provides a reusable Latte widget for language switching. When project file copying is handled by drago-ex/project-tools, the widget is copied to:

Import the widget in your layout:

Render language links:

The current language link automatically receives the current class.

Available options:

• lang - target language code.
• name - visible translated label.
• class - optional class added to the link.
• tag - optional wrapper tag: li, div, or span.
• tagClass - optional class added to the wrapper tag.

Use class when the link needs a custom class:

Use tag when the link must be wrapped, for example in a dropdown menu:

Use tagClass when the wrapper needs styling:

Notes

• Composer package translation directories are discovered from extra.drago-translator.translation.
• Each Composer package declares one translation directory.
• The root project can declare its own translation directory using the same metadata.
• Manual translateDirs remain available for exceptional cases.
• Translations are loaded lazily on first use.
• Missing keys return the original message.