timebank-cc-public/references/translations/PLATFORM_TRANSLATIONS.md

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:

'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

{{-- 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

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

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":

'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:

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:

php artisan tinker

// 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

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