Translating Add-on Content

Overview

Each Larapen add-on (Blog, Shop, HelpCenter, etc.) comes with its own set of translation files, separate from the core application. This guide explains how to locate, translate, and keep add-on translations in sync.

Where add-on translation files are located

Add-on translations follow the same PHP array format as core translations, but they live inside each add-on's directory:

extensions/addons/{addon-name}/resources/lang/
├── en/
│   └── {addon-name}.php      ← English translations (reference)
├── fr/
│   └── {addon-name}.php      ← French translations
└── de/
    └── {addon-name}.php      ← German translations (after adding German)

Examples

extensions/addons/blog/resources/lang/en/blog.php
extensions/addons/blog/resources/lang/fr/blog.php

extensions/addons/shop/resources/lang/en/shop.php
extensions/addons/shop/resources/lang/fr/shop.php

extensions/addons/helpcenter/resources/lang/en/helpcenter.php
extensions/addons/helpcenter/resources/lang/fr/helpcenter.php

How add-on translations work

Automatic scaffolding

When you add a new language in the admin panel (Settings → Languages → Add Language), Larapen automatically:

1. Scans all installed add-ons in extensions/addons/.
2. For each add-on that has an en/ translation directory, copies those files to the new language's directory.
3. The copied files contain the English text as placeholders, ready for you to translate.

For example, if you add German (de) and have the Blog and Shop add-ons installed, Larapen creates:

• extensions/addons/blog/resources/lang/de/blog.php
• extensions/addons/shop/resources/lang/de/shop.php

Translation key format

Add-on translations use a namespaced format. The namespace is the add-on name:

// In Blade templates and PHP code, add-on translations are accessed as:
__('blog::blog.posts.title')          // Blog add-on: "posts.title" key
__('shop::shop.products.add_to_cart') // Shop add-on: "products.add_to_cart" key
__('helpcenter::helpcenter.tickets.new')  // HelpCenter add-on: "tickets.new" key

The double-colon (::) separates the add-on namespace from the translation key. You don't need to worry about this when translating; just translate the values in the PHP files.

How to translate add-on files

Step 1: Locate the file

Navigate to the add-on's translation directory:

extensions/addons/{addon-name}/resources/lang/{your-language-code}/

Open the PHP file in a text editor.

Step 2: Translate the values

The file structure is identical to core translation files; a PHP array where you replace English values with your translations:

<?php

declare(strict_types=1);

return [
    'posts' => [
        'title'       => 'Blog Posts',      // ← Replace with translation
        'add_new'     => 'New Post',         // ← Replace with translation
        'edit'        => 'Edit Post',        // ← Replace with translation
        'published'   => 'Published',        // ← Replace with translation
        'draft'       => 'Draft',            // ← Replace with translation
        'view_count'  => ':count views',     // ← Keep :count placeholder!
    ],
    'categories' => [
        'title'       => 'Categories',
        'add_new'     => 'New Category',
    ],
    // ...
];

Step 3: Save with UTF-8 encoding

Always save the file with UTF-8 encoding (without BOM) to ensure special characters display correctly.

Keeping add-on translations in sync

When an add-on is updated to a new version, it may include new translation keys in its English files. To synchronize all languages:

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

This will:

• Add any new keys from the English add-on files to all other languages (with English text as placeholder).
• Remove any obsolete keys that no longer exist in the English files.
• Preserve all existing translations in every language.
• Process all installed add-ons in a single operation.

AI-powered translation for add-ons

The AI-powered batch translation feature (available at Settings → Languages) also translates add-on files. When you click "AI Translate" for a language, the system processes both core and add-on translation files in a single operation. This is the fastest way to translate all add-on content for a new language.

Add-on translations and themes

Add-on translation files are independent of themes. When you switch themes, the same add-on translations are used regardless of which theme is active. The theme controls the visual presentation (layout, styles), while translation files control the text content.

Translation priority

When Larapen looks up a translation for an add-on, it checks in this order:

1. Add-on translation file for the current language: extensions/addons/{addon}/resources/lang/{locale}/{addon}.php
2. Add-on translation file for the fallback language (usually English): extensions/addons/{addon}/resources/lang/en/{addon}.php
3. If no translation is found, the translation key itself is displayed.

Troubleshooting

Translation not appearing

• Verify the file exists at the correct path: extensions/addons/{addon}/resources/lang/{code}/{addon}.php
• Check that the file returns a valid PHP array (no syntax errors).
• Clear the application cache: Settings → Cache → Clear All.

Missing translation files for a new language

• Run "Sync Translation Files" from Settings → Languages.
• Or manually copy the en/ directory to your new language code: cp -r extensions/addons/{addon}/resources/lang/en/ extensions/addons/{addon}/resources/lang/{code}/

Add-on installed after language was created

If you install an add-on after you've already added a language, the add-on's translation files may not have been scaffolded for that language. Simply run "Sync Translation Files" to create the missing files.