Download the PHP package brunoscode/twill-translation-handler without Composer

Twill Translation Handler

A Twill CMS capsule for managing Laravel translations directly from the admin panel. Built on top of LaravelTranslationHandler.

Twill compatibility: Currently supports Twill 3 (Laravel 11–12, PHP 8.2+). Twill 2 support is available in the v0.x releases.

Supported versions

Features

• Translation key management — Browse and edit all translation keys and their per-locale values from a clean Twill module interface.
• Group-based organization — Translations are automatically grouped by prefix (e.g. messages, messages.validation). Groups are created automatically on import and provide a focused editing view via Twill repeaters.
• Multi-locale support — Edit translations for all configured locales side by side. Individual locale values can be marked active or inactive.
• Import / Export — Sync translations between the database and CSV files:
  • Import from PHP files to populate the database
  • Export all translations to CSV or upload a CSV to import
  • Export a single group as CSV directly from its edit page
• Automatic group syncing — When translations are imported, the DatabaseHandler automatically creates all intermediate group levels (e.g. importing messages.validation.required creates both messages and messages.validation groups).
• Auto-sync to PHP files — Saving a translation key or a group automatically exports the affected PHP language file, keeping the filesystem always in sync with the database.

Requirements

• PHP 8.2, 8.3, or 8.4
• Laravel 11 or 12
• Twill 3.x
• brunoscode/laravel-translation-handler ^2.1

Installation

Run the migrations:

Publish the config file:

Optionally publish the views to customise them:

Navigation

The package provides three sub-pages:

• Translations — browse and edit individual translation keys
• Groups — edit translations grouped by prefix
• Import / Export — sync translations via CSV

TwillNavigation builder

If your app uses the newer TwillNavigation builder API, disable the automatic registration in config/translation-handler.php:

Then register the entries in your AppServiceProvider (or wherever you build your Twill navigation):

If you have a custom admin_route_name_prefix, replace twill. accordingly:

Legacy twill-navigation config array

By default the package registers the navigation automatically via the legacy twill-navigation config array. The package will merge the translations key into the array at boot. To control where it appears in the sidebar, add an empty placeholder in the right position — PHP arrays preserve the insertion order of existing keys:

Configuration

See LaravelTranslationHandler for the full list of configuration options.

Usage

Once installed, a Translations section will appear in the Twill admin navigation with three pages:

Keys

Lists all translation keys stored in the database. Each key can be opened to edit its translated value for every configured locale. Translation keys are managed exclusively through import — manual creation is intentionally disabled to keep the database in sync with source files.

Groups

Lists all translation groups, auto-generated from the key prefixes. Opening a group shows all matching keys in a repeater, allowing batch editing of every locale's value from a single form.

Import / Export

A tools page with actions to sync translations:

Per-group CSV export is also available directly from each group's edit page.

CSV import rules

• The file does not need to contain all keys — only the keys present in the file will be updated.
• All locale columns must be present in the file header.
• Empty values will overwrite the existing translation with an empty string.

PHP language files are kept in sync automatically: every import (CSV via the tools page or per-group) writes the affected PHP files immediately after updating the database. Saving a single key or group from the edit form also triggers the same export.

Editorial interface

Editing a key

Opening a translation key shows:

Saving a key immediately exports the affected PHP language file.

Editing a group

Opening a group shows the prefix (read-only) and one textarea per translation key that belongs to the group. Each textarea is translatable — every configured locale is available as a tab. A Download CSV button lets editors export the group directly from the edit page.

Field naming: each textarea is internally keyed as trans_<id> where <id> is the translation_keys.id. This is transparent to editors but relevant if you extend the form.

Saving a group writes all locale values and immediately exports the affected PHP language file.

allow_empty

Both modules show an Allow empty checkbox in the sidebar. Its effect is on form validation:

When a value reaches the repository as null (e.g. the editor cleared a field), it is normalised to an empty string before being persisted. This means the database never stores null in translation_values.value through a form save.

Deployment

The database is the source of truth for translation values. PHP language files are used only to carry new keys and new locales between environments.

A typical deploy script:

The first command (without --force) inserts only keys and locale entries that do not yet exist in the DB — existing values are left untouched. The second command rewrites the PHP files so they always reflect the DB state.

First deploy / fresh environment: if the DB is empty, seed it from the PHP files:

Syncing translations from production

When content editors have updated translations directly in production or staging, you can pull those changes back into the repository:

1. Download the CSV from the production admin panel via Translations → Import / Export → Export to CSV.

2. Copy the file into your project (e.g. storage/lang/translations.csv) and import it to regenerate the PHP files:

3. Commit the updated PHP files and push:

The next deploy will import the updated PHP files into any environment whose DB does not yet have those values.

Database Structure

Testing

Changelog

Please see CHANGELOG for recent changes.

Credits

• Bruno Magnani
• All Contributors

License

The MIT License (MIT). Please see License File for more information.