How to Translate Language Files

Overview

Larapen uses two types of translation files to store all the text that appears on your website. When you add a new language, these files are automatically created with English text as placeholders. This guide explains how to find and translate these files.

Understanding translation file types

PHP translation files

PHP files contain grouped translations organized by feature area. They use a key-value structure where each key maps to a translated string.

Location: lang/{language-code}/

Example (lang/de/admin.php):

<?php

declare(strict_types=1);

return [
    'dashboard' => [
        'title'    => 'Dashboard',       // ← Replace with: 'Armaturenbrett'
        'welcome'  => 'Welcome back!',   // ← Replace with: 'Willkommen zurück!'
    ],
    'pages' => [
        'title'    => 'Pages',           // ← Replace with: 'Seiten'
        'add_new'  => 'Add New',         // ← Replace with: 'Neu hinzufügen'
    ],
    // ... more keys
];

JSON translation files

JSON files contain short, standalone strings used primarily on the front-end: button labels, validation messages, and brief UI text.

Location: lang/{language-code}.json

Example (lang/de.json):

{
    "Home": "Startseite",
    "Contact": "Kontakt",
    "Read More": "Mehr lesen",
    "Submit": "Absenden",
    "Search...": "Suchen...",
    "No results found.": "Keine Ergebnisse gefunden."
}

File structure

Here is the complete translation file structure for a language (e.g., German de):

lang/
├── de/                         ← PHP translation files
│   ├── admin.php               ← Admin panel strings
│   ├── front.php               ← Front-end strings
│   ├── auth.php                ← Authentication strings
│   ├── validation.php          ← Form validation messages
│   ├── installer.php           ← Installation wizard strings
│   └── account.php             ← User account strings
├── de.json                     ← JSON front-end short strings
│
├── en/                         ← English (reference: do not modify)
│   ├── admin.php
│   ├── front.php
│   └── ...
└── en.json

Add-on translation files

Each installed add-on also has its own translation files:

extensions/addons/blog/resources/lang/
├── de/
│   └── blog.php                ← Blog add-on strings
├── en/
│   └── blog.php
└── fr/
    └── blog.php

extensions/addons/shop/resources/lang/
├── de/
│   └── shop.php                ← Shop add-on strings
├── en/
│   └── shop.php
└── fr/
    └── shop.php

How to translate

Step 1: Identify the files to translate

After adding a new language, you need to translate:

Step 2: Edit the translation files

You can edit translation files using any of these methods:

Method A: Via FTP / File Manager

1. Connect to your server via FTP or use your hosting panel's File Manager.
2. Navigate to the lang/{code}/ directory.
3. Download the file you want to translate.
4. Open it in a plain text editor (Notepad++, VS Code, Sublime Text: not Microsoft Word).
5. Replace the English values with your translations.
6. Save the file with UTF-8 encoding (important for special characters).
7. Upload the translated file back to the server.

Method B: Via SSH

# Edit a PHP translation file
nano lang/de/front.php

# Edit the JSON translation file
nano lang/de.json

Step 3: Translation rules

Example with placeholders:

// English (DO NOT translate the :name placeholder)
'welcome' => 'Welcome, :name!',

// German (keep :name exactly as is)
'welcome' => 'Willkommen, :name!',

Synchronizing translation files

When Larapen is updated to a new version, new translation keys may be added to the English files. To add these missing keys to your translation files:

1. Go to Settings → Languages in the admin panel.
2. Click the "Sync Translation Files" button.

This operation:

• Adds any new keys that exist in English but are missing from your language files (using the English text as a placeholder).
• Removes any obsolete keys that no longer exist in English files.
• Preserves all your existing translations; nothing you've translated is lost or overwritten.
• Processes both core translation files and add-on translation files.

AI-powered batch translation

For a faster alternative to manual translation, Larapen includes an AI-powered batch translation feature that can translate all language files automatically:

1. Go to Settings → Languages in the admin panel.
2. Click the "AI Translate" button next to the language you want to translate.
3. The system uses the configured AI provider to translate all core and add-on translation files at once.

This requires an AI provider to be configured in Settings → AI (e.g., OpenAI, Anthropic, Google). The AI translations provide a solid starting point, but we recommend reviewing them for accuracy and adjusting domain-specific or context-dependent terms.

Tips for efficient translation

• Start with front-end files (front.php and .json): these are what your visitors see.
• Use the English files as reference: keep lang/en/ open alongside the file you're translating.
• Translate in context: browse your website in the new language to see how translations look in context and adjust as needed.
• Keep translations concise: some languages produce longer text than English. Test that your translations fit within buttons, menus, and table headers.
• Handle pluralization: Laravel supports plural forms. If you see keys with | separators (e.g., '1 item|:count items'), translate both forms.
• Use AI then refine: Use the AI-powered batch translation to get a first pass, then manually review and refine critical user-facing strings.