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:

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