Initial commit
This commit is contained in:
Ronald Huynen
258
references/translations/PLATFORM_TRANSLATIONS.md
Normal file
258
references/translations/PLATFORM_TRANSLATIONS.md
Normal file
@@ -0,0 +1,258 @@
|
||||
# Platform Translation System
|
||||
|
||||
## Overview
|
||||
|
||||
This system allows dynamic customization of platform-specific terminology (like "Timebank.cc", "Timebanker", etc.) across all languages without hardcoding values in translation files.
|
||||
|
||||
## Configuration
|
||||
|
||||
Platform translations are defined in `config/timebank-cc.php` under the `platform_translations` array:
|
||||
|
||||
```php
|
||||
'platform_translations' => [
|
||||
'en' => [
|
||||
'platform_name' => ' Timebank.cc',
|
||||
'platform_name_legal' => 'association Timebank.cc',
|
||||
'platform_name_short' => 'Timebank',
|
||||
'platform_slogan' => 'Your time is currency',
|
||||
'platform_user' => 'Timebanker',
|
||||
'platform_users' => 'Timebankers',
|
||||
'platform_principles' => 'Timebank principles',
|
||||
],
|
||||
'nl' => [
|
||||
// Dutch translations...
|
||||
],
|
||||
// ... other languages
|
||||
],
|
||||
```
|
||||
|
||||
## Helper Functions
|
||||
|
||||
Located in `app/Helpers/PlatformConfig.php`:
|
||||
|
||||
### Core Function
|
||||
|
||||
- **`platform_trans($key, $locale = null, $default = null)`**
|
||||
- Get any platform translation by key
|
||||
- Falls back to base language (English) if not found in current locale
|
||||
- Example: `platform_trans('platform_users')` → "Timebankers"
|
||||
|
||||
### Convenience Functions
|
||||
|
||||
- **`platform_name($locale = null)`** → " Timebank.cc"
|
||||
- **`platform_name_short($locale = null)`** → "Timebank"
|
||||
- **`platform_name_legal($locale = null)`** → "association Timebank.cc"
|
||||
- **`platform_slogan($locale = null)`** → "Your time is currency"
|
||||
- **`platform_user($locale = null)`** → "Timebanker" (singular)
|
||||
- **`platform_users($locale = null)`** → "Timebankers" (plural)
|
||||
- **`platform_principles($locale = null)`** → "Timebank principles"
|
||||
- **`platform_currency_name($locale = null)`** → "Hour" (singular)
|
||||
- **`platform_currency_name_plural($locale = null)`** → "Hours" (plural)
|
||||
- **`platform_currency_symbol($locale = null)`** → "H"
|
||||
|
||||
### Automatic Placeholder Replacement
|
||||
|
||||
- **`trans_with_platform($key, $replace = [], $locale = null)`**
|
||||
- Translates a string and replaces platform placeholders
|
||||
- Supports all standard Laravel `__()` parameters
|
||||
|
||||
## Translation File Placeholders
|
||||
|
||||
JSON translation files use placeholders that get replaced at runtime:
|
||||
|
||||
| Placeholder | Replaced With | Example |
|
||||
|------------|---------------|---------|
|
||||
| `@PLATFORM_NAME@` | platform_name() | " Timebank.cc" |
|
||||
| `@PLATFORM_NAME_SHORT@` | platform_name_short() | "Timebank" |
|
||||
| `@PLATFORM_NAME_LEGAL@` | platform_name_legal() | "association Timebank.cc" |
|
||||
| `@PLATFORM_SLOGAN@` | platform_slogan() | "Your time is currency" |
|
||||
| `@PLATFORM_USER@` | platform_user() | "Timebanker" |
|
||||
| `@PLATFORM_USERS@` | platform_users() | "Timebankers" |
|
||||
| `@PLATFORM_PRINCIPLES@` | platform_principles() | "Timebank principles" |
|
||||
| `@PLATFORM_CURRENCY_NAME@` | platform_currency_name() | "Hour" |
|
||||
| `@PLATFORM_CURRENCY_NAME_PLURAL@` | platform_currency_name_plural() | "Hours" |
|
||||
| `@PLATFORM_CURRENCY_SYMBOL@` | platform_currency_symbol() | "H" |
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### In Blade Templates
|
||||
|
||||
```blade
|
||||
{{-- Direct helper usage --}}
|
||||
<h1>Welcome to {{ platform_name() }}!</h1>
|
||||
<p>Join {{ platform_users() }} worldwide</p>
|
||||
|
||||
{{-- With translation placeholders --}}
|
||||
<p>{{ trans_with_platform('Activities or skills you offer to other @PLATFORM_USERS@') }}</p>
|
||||
|
||||
{{-- Force specific locale --}}
|
||||
<p>{{ platform_name('de') }}</p> {{-- German version --}}
|
||||
```
|
||||
|
||||
### In PHP Controllers/Classes
|
||||
|
||||
```php
|
||||
use Illuminate\Support\Facades\Mail;
|
||||
|
||||
// In email subject
|
||||
$subject = 'Welcome to ' . platform_name() . '!';
|
||||
|
||||
// With translations
|
||||
$message = trans_with_platform('Your profile on @PLATFORM_NAME@ just received a star');
|
||||
|
||||
// Get translation for specific locale
|
||||
$germanSlogan = platform_slogan('de'); // "Deine Zeit ist Währung"
|
||||
```
|
||||
|
||||
### In Livewire Components
|
||||
|
||||
```php
|
||||
public function mount()
|
||||
{
|
||||
$this->pageTitle = platform_users();
|
||||
$this->welcomeMessage = trans_with_platform('Welcome new @PLATFORM_USER@!');
|
||||
}
|
||||
```
|
||||
|
||||
## Language Support
|
||||
|
||||
Platform translations are available in:
|
||||
|
||||
- **English (en)** - Base language
|
||||
- **Dutch (nl)** - Nederlandse vertalingen
|
||||
- **German (de)** - Deutsche Übersetzungen
|
||||
- **Spanish (es)** - Traducciones al español
|
||||
- **French (fr)** - Traductions françaises
|
||||
|
||||
## Customization Guide
|
||||
|
||||
### Changing Platform Terminology
|
||||
|
||||
1. Edit `config/timebank-cc.php`
|
||||
2. Update the `platform_translations` array for each language
|
||||
3. Clear config cache: `php artisan config:clear`
|
||||
|
||||
Example - Rebranding to "TimeCurrency":
|
||||
|
||||
```php
|
||||
'platform_translations' => [
|
||||
'en' => [
|
||||
'platform_name' => 'TimeCurrency',
|
||||
'platform_name_short' => 'TimeCurrency',
|
||||
'platform_user' => 'TimeCurrency member',
|
||||
'platform_users' => 'TimeCurrency members',
|
||||
// ... update other keys
|
||||
],
|
||||
// ... repeat for all languages
|
||||
],
|
||||
```
|
||||
|
||||
### Adding New Languages
|
||||
|
||||
1. Add new locale to `platform_translations` in config
|
||||
2. Provide translations for all keys
|
||||
3. Create corresponding JSON translation file in `resources/lang/`
|
||||
|
||||
## Migration to Database
|
||||
|
||||
When ready to move configuration to database:
|
||||
|
||||
1. Create migration for `platform_translations` table
|
||||
2. Seed table with current config values
|
||||
3. Update `platform_trans()` function in `app/Helpers/PlatformConfig.php`:
|
||||
|
||||
```php
|
||||
function platform_trans($key, $locale = null, $default = null)
|
||||
{
|
||||
$locale = $locale ?? app()->getLocale();
|
||||
|
||||
// Query database instead of config
|
||||
$translation = DB::table('platform_translations')
|
||||
->where('key', $key)
|
||||
->where('locale', $locale)
|
||||
->value('value');
|
||||
|
||||
// Fallback logic remains the same
|
||||
if ($translation === null && $locale !== $baseLanguage) {
|
||||
$translation = DB::table('platform_translations')
|
||||
->where('key', $key)
|
||||
->where('locale', $baseLanguage)
|
||||
->value('value');
|
||||
}
|
||||
|
||||
return $translation ?? $default ?? $key;
|
||||
}
|
||||
```
|
||||
|
||||
All existing code will continue working without modification!
|
||||
|
||||
## Testing
|
||||
|
||||
Test helpers across all locales:
|
||||
|
||||
```bash
|
||||
php artisan tinker
|
||||
```
|
||||
|
||||
```php
|
||||
// Test English
|
||||
app()->setLocale('en');
|
||||
echo platform_users(); // "Timebankers"
|
||||
|
||||
// Test Dutch
|
||||
app()->setLocale('nl');
|
||||
echo platform_users(); // "Timebankers"
|
||||
echo platform_principles(); // "Timebank principes"
|
||||
|
||||
// Test German
|
||||
app()->setLocale('de');
|
||||
echo platform_users(); // "Zeitbankers"
|
||||
echo platform_slogan(); // "Deine Zeit ist Währung"
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Placeholders not being replaced
|
||||
|
||||
- Ensure you're using `trans_with_platform()` instead of `__()`
|
||||
- Check that placeholder syntax is correct: `@PLATFORM_NAME@` (not `{PLATFORM_NAME}`)
|
||||
|
||||
### Wrong language returned
|
||||
|
||||
- Check current locale: `app()->getLocale()`
|
||||
- Verify translation exists in config for that locale
|
||||
- Fallback to English if translation missing
|
||||
|
||||
### Autoload issues
|
||||
|
||||
```bash
|
||||
composer dump-autoload
|
||||
php artisan config:clear
|
||||
php artisan cache:clear
|
||||
```
|
||||
|
||||
## File Reference
|
||||
|
||||
- **Helper**: `app/Helpers/PlatformConfig.php`
|
||||
- **Config**: `config/timebank-cc.php` (platform_translations section)
|
||||
- **Translations**: `resources/lang/{locale}.json`
|
||||
- **Backups**: `resources/lang/{locale}.json.bak`
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Always use helpers** in new code instead of hardcoding "Timebank.cc"
|
||||
2. **Use `trans_with_platform()`** when displaying translated strings with platform terms
|
||||
3. **Test all locales** when changing platform terminology
|
||||
4. **Document custom terms** in comments when creating new translation keys
|
||||
5. **Keep backups** of JSON files before major changes
|
||||
|
||||
## Examples in Codebase
|
||||
|
||||
See these files for reference implementations:
|
||||
- Translation files: `resources/lang/nl.json` (lines with @PLATFORM placeholders)
|
||||
- Test examples: Run `php artisan tinker` and use code from Testing section above
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-10-23
|
||||
**Version**: 1.0
|
||||
Reference in New Issue
Block a user