# Translations
This guide will walk you through configuring PanelAlpha in multiple languages. While PanelAlpha defaults to English, the client area can be fully customized and translated into any desired language.
# Overview
PanelAlpha supports multilingual configurations through language files that control:
- Client area interface - All user-facing text and menus
- Email templates - Automated notifications and communications
- Admin area messages - System messages and notifications
The system automatically detects RTL (right-to-left) languages and adjusts the interface accordingly.
# Language File Structure
Language files are stored in the /opt/panelalpha/app/packages/api/resources/lang directory. Each language has its own subdirectory containing:
- api - API message translations
- clientarea/translation.json - Client area interface translations
- email-templates - Email template files
- auth.php, pagination.php, passwords.php, validation.php - System files
# Directory Permissions
Important: Ensure proper permissions for translation directories:
chmod 755 /opt/panelalpha/app/packages/api/resources/lang/{language_code}
chmod 755 /opt/panelalpha/app/packages/api/resources/lang/{language_code}/api
chmod 755 /opt/panelalpha/app/packages/api/resources/lang/{language_code}/clientarea
chmod 755 /opt/panelalpha/app/packages/api/resources/lang/{language_code}/email-templates
Replace {language_code} with your target language code (e.g., de, es, fr).
# Available Translations
Ready-made translations are available from the PanelAlpha GitHub repository (opens new window). Currently supported languages include:
- German (de) - Deutsche Übersetzung
- Spanish (es) - Traducción en español
- French (fr) - Traduction française
- Italian (it) - Traduzione italiana
- Brazilian Portuguese (pt_BR) - Tradução em português brasileiro
Each language package contains:
- Client area interface translations
- Email template translations
- README file with installation instructions
Important: These translations were prepared using automated tools. We recommend reviewing them before production use and contributing improvements back to the community.
# Installation
You can install the translations either using an automatic script or manually. Read below for details.
Automatic Installation
To automatically install and use these translations with PanelAlpha, follow these steps:
- Download the script to
/opt/panelalpha:curl -sL -o /opt/panelalpha/sync-translations.sh https://raw.githubusercontent.com/panelalpha/PanelAlpha-Translations/refs/heads/main/scripts/sync-translations.sh - Run the script with the desired language, remember to replace
{language_code}with the actual language code of the available translations de, es, fr, it or pt_BR.bash /opt/panelalpha/sync-translations.sh --lang "{language_code}"
Manual Installation
To manually install and use these translations with PanelAlpha, follow these steps:
- Download the translation files - Download the language files for your desired language from the repository.
- Copy files to the server - Copy the translation files to your server’s language directory.
- Set appropriate permissions - Ensure the correct permissions are set for the translation files. Run the below command, but remember to replace
{language_code}with the actual language code of the available translations de, es, fr, it or pt_BR.
chmod -R 755 /opt/panelalpha/app/packages/api/resources/lang/<language_code>
- Synchronize notifications - Run the following command to sync notifications with the new translations:
docker compose -f /opt/panelalpha/app/docker-compose.yml exec -T api php artisan notifications:sync
- Configure the client area language:
- See the instructions below (see point "Changing the client area language") on how to change the client area language. Changing the language for a client will also change the language of the email templates. For example, if your client selects German for the client area, all email templates will also be sent in German.
# Contributing
If you would like to contribute updates to existing translations or provide new translations, you are welcome to do so at any time. Simply sign in to your GitHub account and visit the PanelAlpha Translations Repository (opens new window).
Editing Existing Translations:
Fork the repository - Ensure you are signed in to your GitHub account, then fork the repository to create a copy under your account.
Make your changes - Edit the translation files you want to update in your forked repository.
Commit the changes - After making your edits, press "Commit Changes" to save them in a new branch.
Describe your changes - Provide a detailed description of your updates. This helps us verify and approve your contribution for public use. Press "Propose Changes."
Submit a pull request - Review your changes and create a pull request. This notifies us of your contribution, and we will review and publish it for other users.
Adding a Translation for an Unavailable Language:
Add a new file - Fork the repository, then create a new file for the language you're contributing.
Create the language path - Use the appropriate language code (e.g., cze for Czech) to create a new folder and file path for your translation.
Provide translations - Use the original files as a reference. Ensure you only modify the right side of the = sign, leaving the structure on the left unchanged.
Commit the changes - Once you’ve added the translations, press "Commit Changes." Provide an extended description of your additions, then press "Propose Changes."
Submit a pull request - Review your changes and submit a pull request. We will be notified, verify your contribution, and publish it for public use.
# Language Configuration
# Admin Area Configuration
Set the default language for all clients through the admin area:
- Navigate to Configuration → General → Client Area
- Select Default Language from the dropdown menu
- Save the configuration
This language will be applied to all new client registrations and serve as the fallback language.
# Client Area Language Selection
Clients can choose their preferred language in several ways:
# Login Page Selection
Clients can select their preferred language directly on the login page:
# Footer Language Selector
A language dropdown is available in the client area footer:
# Account Settings
Clients can change their language preference in their account settings:
- Navigate to Account Details → Personal Information
- Select Language from the dropdown menu
- Save changes
Note: When a client changes their language preference, it affects both the client area interface and email notifications they receive.
# Troubleshooting
# Common Issues
# Permissions Errors
Problem: Translation files not loading Solution: Verify directory permissions are set to 755:
chmod -R 755 /opt/panelalpha/app/packages/api/resources/lang/{language_code}
# Missing Translations
Problem: Some text still appears in English Solution: Check for missing keys in translation files and ensure all required files are present
# Notifications Not Translated
Problem: Email notifications still in default language Solution: Run the notifications sync command:
docker compose -f /opt/panelalpha/app/docker-compose.yml exec -T api php artisan notifications:sync
# Language Not Appearing in Dropdown
Problem: New language doesn't show in language selection Solution:
- Verify proper directory structure
- Check file permissions
- Restart PanelAlpha containers if necessary
# Getting Help
If you encounter translation issues:
- Check the Troubleshooting Center for common solutions
- Review file permissions and directory structure
- Verify all required translation files are present
- Contact our support team (opens new window) for assistance