winbigfox 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:
- Take the original English text.
- Convert it to lowercase.
- Use that lowercase text as the translation key.
- Add the key to
/lang/en/app.php. - Add the same key to all other supported locale files.
- 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.',
];