How to Add a New Language

5 min read Last updated Mar 24, 2026 3 views

Overview

Larapen supports unlimited languages out of the box. English and French are included with every installation, but you can add any language; including right-to-left (RTL) languages like Arabic and Hebrew; directly from the admin panel.

When you add a new language, Larapen automatically creates all the necessary translation files by copying the English files as a starting point. You can then translate these files at your own pace.

Adding a new language

Step 1: Open the Languages page

Log into your admin panel at https://yoursite.com/admin.
Go to Settings → Languages.
Click the "Add Language" button.

Step 2: Fill in the language details

Field	Description	Example
Code (required)	The ISO 639-1 language code. This is the standard 2-letter code for the language.	`de` for German, `es` for Spanish, `ar` for Arabic
Name (auto-filled)	The English name of the language. This is automatically filled in when you enter the code.	German, Spanish, Arabic
Native Name (required)	The name of the language in its own script. This is shown in the language switcher.	Deutsch, Español, العربية
Direction (required)	Text direction: Left-to-Right (LTR) for most languages, or Right-to-Left (RTL) for Arabic, Hebrew, etc.	LTR or RTL
Flag Icon (optional)	A 2-letter country code used to display a flag icon next to the language name.	`de` for Germany, `es` for Spain, `sa` for Saudi Arabia
Position	The display order in the language list and language switcher. Lower numbers appear first.	0, 1, 2, ...
Active	Whether this language is available on the website. You can add a language and keep it inactive while you work on translations.	Checked / Unchecked
Set as Default	Make this the default language for your website. Only one language can be the default.	Checked / Unchecked

Step 3: Save

Click "Save". Larapen will:

Create the language record in the database.
Automatically scaffold all translation files by copying English (en) files as a starting point:
- Core translation files: lang/{code}/ (PHP files) and lang/{code}.json
- Add-on translation files: extensions/addons/*/resources/lang/{code}/ (for each installed add-on)

Note: Existing translation files are never overwritten. If you've already placed translation files on the server before adding the language, they will be preserved.

After adding a language

Translate the files

The newly created translation files contain the English text as placeholders. You need to replace each English string with the corresponding translation. See the "How to Translate Language Files" article for detailed instructions.

Use AI-powered batch translation (optional)

Instead of translating files manually, you can use the AI-powered batch translation feature to automatically translate all language files at once:

Go to Settings → Languages in the admin panel.
Click the "AI Translate" button next to the language you want to translate.
The system will use the configured AI provider to translate all core and add-on translation files into the selected language.

Note: The AI translation feature requires a configured AI provider. Go to Settings → AI to select a provider (e.g., OpenAI, Anthropic, Google) and enter your API key. AI translations are a good starting point, but we recommend reviewing them for accuracy, especially for domain-specific terminology.

Activate when ready

If you created the language as inactive (to work on translations first), activate it when you're ready:

Go to Settings → Languages.
Click "Edit" on the language.
Check the "Active" checkbox.
Click "Update".

Once active, the language will appear in the front-end language switcher and visitors can browse your site in that language.

Test the language

After activating the new language:

Visit your website and use the language switcher to switch to the new language.
Check that the URL includes the language prefix (e.g., https://yoursite.com/de/).
Verify that translated strings appear correctly throughout the site.
Check that translatable content (pages, portfolio items, etc.) shows the correct translation when available.

Editing a language

To modify a language's settings after creation:

Go to Settings → Languages.
Click "Edit" on the language you want to modify.
You can change: name, native name, direction, flag icon, system locale, date/time formats, position, and active status.
The language code cannot be changed after creation.

Additional fields available when editing

Field	Description
System Locale	The operating system locale used for date/number formatting (e.g., `de_DE`, `es_ES`). Usually auto-detected.
Date Format	PHP date format for this language (e.g., `d.m.Y` for German, `d/m/Y` for French). Uses the site default if left empty.
Date & Time Format	PHP datetime format for this language (e.g., `d.m.Y H:i`). Uses the site default if left empty.

Deleting a language

Go to Settings → Languages.
Click the delete button (trash icon) next to the language.
Confirm the deletion.

Important: You cannot delete the default language. To delete a language that is currently the default, first set a different language as the default, then delete it.

Note: Translation files for English (en) and French (fr) are never deleted, as they are part of the core distribution.