Laravel Translation Skill

This skill defines how translations must be handled in Laravel applications.

Goal

Translations must be stored in the standard Laravel language files:

/lang/{locale}/app.php

Examples:

/lang/en/app.php
/lang/de/app.php
/lang/fr/app.php

All application UI strings should use the app.php translation file unless there is a strong project-specific reason to use another file.

Translation Key Rule

The translation key must always be the English lowercase version of the source text.

The key should be:

• written in English
• fully lowercase
• identical across all languages
• based on the full source sentence or phrase
• stored as a plain string key in app.php

Do not use artificial keys such as:

'new_version_available' => '...'
'app.update.message' => '...'
'version.new_available' => '...'

Instead, use the English lowercase text itself as the key.

Example

/lang/en/app.php

<?php

return [
    'a new version of the app is available. please install the latest version to enjoy new features and improvements.' => 'A new version of the app is available. Please install the latest version to enjoy new features and improvements.',
];

/lang/de/app.php

<?php

return [
    'a new version of the app is available. please install the latest version to enjoy new features and improvements.' => 'Eine neue Version der App ist verfügbar. Bitte installiere die neueste Version, um neue Funktionen und Verbesserungen zu nutzen.',
];

Usage in Laravel

Translations should be referenced using Laravel’s translation helper:

__('app.a new version of the app is available. please install the latest version to enjoy new features and improvements.')

or with trans():

trans('app.a new version of the app is available. please install the latest version to enjoy new features and improvements.')

Adding a New Translation

When adding a new translatable string:

1. Take the original English text.
2. Convert it to lowercase.
3. Use that lowercase text as the translation key.
4. Add the key to /lang/en/app.php.
5. Add the same key to all other supported locale files.
6. Translate only the value, never the key.

Example source text:

Project was created successfully.

Translation key:

project was created successfully.

/lang/en/app.php

<?php

return [
    'project was created successfully.' => 'Project was created successfully.',
];

/lang/de/app.php

<?php

return [
    'project was created successfully.' => 'Das Projekt wurde erfolgreich erstellt.',
];

Placeholders

Laravel placeholders may be used as usual.

The placeholder names must stay unchanged across all languages.

/lang/en/app.php

<?php

return [
    'hello :name, your project was updated.' => 'Hello :name, your project was updated.',
];

/lang/de/app.php

<?php

return [
    'hello :name, your project was updated.' => 'Hallo :name, dein Projekt wurde aktualisiert.',
];

Usage:

__('app.hello :name, your project was updated.', ['name' => $user->name])

Tone and Style

Translations should be natural and user-friendly.

For German translations:

• use informal address unless the project explicitly requires formal language
• prefer clear, simple wording
• avoid overly technical terms where a simpler phrase works
• keep the meaning close to the English source
• do not translate placeholders
• keep punctuation natural for the target language

Example:

'delete project' => 'Projekt löschen',

not:

'delete project' => 'Lösche Projekt',

unless the UI context specifically requires an imperative sentence.

Consistency Rules

When updating translations:

• never change an existing key unless the English source meaning changed intentionally
• keep the same key in every locale file
• avoid duplicate keys with slightly different wording
• check whether a similar translation already exists before adding a new one
• preserve placeholders exactly
• preserve HTML, Markdown, or formatting tokens if present

Formatting

Translation files must use valid PHP array syntax:

<?php

return [
    'english lowercase key' => 'Translated value',
];

Use single quotes for keys and values unless escaping would make the string harder to read.

Example with apostrophe:

<?php

return [
    'don\'t show this again' => 'Don\'t show this again',
];

If a translation contains many apostrophes, double quotes may be used for readability.

Do Not

Do not create translation keys like this:

'button.save' => 'Save',
'settings.title' => 'Settings',
'user_created_successfully' => 'User created successfully.',

Do not translate the key itself:

// Wrong in /lang/de/app.php
'eine neue version der app ist verfügbar.' => 'Eine neue Version der App ist verfügbar.',

Do not use different keys for different languages.

The key must remain English and lowercase in every locale.

Correct Pattern

// /lang/en/app.php
return [
    'save' => 'Save',
    'settings' => 'Settings',
    'user created successfully.' => 'User created successfully.',
];

// /lang/de/app.php
return [
    'save' => 'Speichern',
    'settings' => 'Einstellungen',
    'user created successfully.' => 'Benutzer wurde erfolgreich erstellt.',
];