# Venue Translation System Documentation
## 🌍 **Complete Multilingual Venue Management System**
### **📖 Overview**
A comprehensive multilingual venue translation system that allows venue owners (B2B clients) to create and manage venue descriptions in all supported system languages. The system provides both admin panel interface and API access for seamless integration.
---
## 🏗️ **System Architecture**
### **Core Components**
1. **VenueTranslation Model** - Database model for storing translations
2. **HasTranslations Trait** - Adds multilingual functionality to Venue model
3. **VenueTranslationService** - Business logic for translation management
4. **Filament Resource** - Admin interface for managing translations
5. **API Controller** - RESTful API for translation operations
6. **Migration** - Database structure for translations and notifications
---
## 🗄️ **Database Structure**
### **venue_translations Table**
```sql
CREATE TABLE venue_translations (
id BIGINT PRIMARY KEY,
venue_id BIGINT NOT NULL,
locale VARCHAR(10) NOT NULL,
name VARCHAR(255) NOT NULL,
description TEXT,
short_description TEXT,
address VARCHAR(255),
city VARCHAR(100),
country VARCHAR(100),
directions TEXT,
amenities TEXT,
policies TEXT,
accessibility_info TEXT,
meta_title VARCHAR(255),
meta_description TEXT,
additional_data JSON,
created_at TIMESTAMP,
updated_at TIMESTAMP,
UNIQUE KEY unique_venue_locale (venue_id, locale),
FOREIGN KEY (venue_id) REFERENCES venues(id) ON DELETE CASCADE
);
```
### **notification_logs Table**
```sql
CREATE TABLE notification_logs (
id BIGINT PRIMARY KEY,
notification_id VARCHAR(255),
notification_type VARCHAR(255),
notifiable_type VARCHAR(255),
notifiable_id BIGINT,
channel VARCHAR(50),
locale VARCHAR(10),
subject VARCHAR(255),
content TEXT,
recipient_email VARCHAR(255),
recipient_phone VARCHAR(50),
status VARCHAR(50),
sent_at TIMESTAMP,
delivered_at TIMESTAMP,
read_at TIMESTAMP,
failed_at TIMESTAMP,
failure_reason TEXT,
template_key VARCHAR(255),
variables JSON,
company_id BIGINT,
metadata JSON,
tracking_id VARCHAR(255) UNIQUE,
opens_count INT DEFAULT 0,
clicks_count INT DEFAULT 0,
last_opened_at TIMESTAMP,
last_clicked_at TIMESTAMP,
user_agent TEXT,
ip_address VARCHAR(45),
bounce_type VARCHAR(50),
bounce_reason TEXT,
complaint_reason TEXT,
unsubscribe_reason TEXT,
created_at TIMESTAMP,
updated_at TIMESTAMP
);
```
---
## 🌐 **Supported Languages**
### **Current Languages**
- **English (en)** - Default language
- **Bulgarian (bg)** - Full translation support
### **Configuration**
```php
// config/app.php
'supported_locales' => [
'en' => 'English',
'bg' => 'Български',
],
```
---
## 🎨 **Admin Interface**
### **Filament Resource Features**
- **Complete Form Interface** - All translation fields with validation
- **Bulk Operations** - Copy translations between languages
- **Status Tracking** - Visual completion indicators
- **Search & Filter** - Find venues by translation status
- **Analytics Dashboard** - Translation completion statistics
### **Form Sections**
1. **Translation Information** - Venue and language selection
2. **Basic Information** - Name, description, short description
3. **Location Information** - Address, city, country, directions
4. **Additional Information** - Amenities, policies, accessibility
5. **SEO Information** - Meta titles and descriptions
6. **Translation Actions** - Copy from English, completion status
### **Quick Actions**
- **Copy from English** - Duplicate English content to other languages
- **Bulk Copy** - Copy English to all missing translations
- **Completion Tracking** - Visual indicators for translation status
- **Analytics View** - Overall translation statistics
---
## 🔌 **API Integration**
### **Authentication**
```bash
# All API endpoints require authentication
Authorization: Bearer {sanctum_token}
```
### **Base URL**
```
https://your-domain.com/api
```
### **Endpoints Overview**
#### **Venue Translations**
```
GET /api/venues/{venue}/translations # Get all translations
GET /api/venues/{venue}/translations/{locale} # Get specific translation
POST /api/venues/{venue}/translations # Create translation
PUT /api/venues/{venue}/translations/{locale} # Update translation
DELETE /api/venues/{venue}/translations/{locale} # Delete translation
POST /api/venues/{venue}/translations/bulk # Bulk create/update
POST /api/venues/{venue}/translations/copy # Copy between locales
GET /api/venues/{venue}/translations/status # Translation status
GET /api/venues/{venue}/translations/export # Export translations
POST /api/venues/{venue}/translations/import # Import translations
```
#### **Global Translation Operations**
```
GET /api/translations/search # Search by translated content
GET /api/translations/analytics # Analytics (admin only)
```
---
## 📝 **API Usage Examples**
### **Get All Translations for Venue**
```bash
curl -X GET "https://your-domain.com/api/venues/1/translations" \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json"
```
### **Create Translation**
```bash
curl -X POST "https://your-domain.com/api/venues/1/translations" \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"locale": "bg",
"name": "Име на обекта",
"description": "Описание на обекта на български език...",
"short_description": "Кратко описание...",
"address": "Адрес на български",
"city": "Град",
"country": "Държава"
}'
```
### **Bulk Update Translations**
```bash
curl -X POST "https://your-domain.com/api/venues/1/translations/bulk" \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"translations": {
"en": {
"name": "Venue Name",
"description": "English description..."
},
"bg": {
"name": "Име на обекта",
"description": "Българско описание..."
}
}
}'
```
### **Copy Translation**
```bash
curl -X POST "https://your-domain.com/api/venues/1/translations/copy" \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"from_locale": "en",
"to_locale": "bg"
}'
```
### **Search Venues by Translated Content**
```bash
curl -X GET "https://your-domain.com/api/translations/search?query=conference&locale=en" \
-H "Authorization: Bearer {token}"
```
---
## 🎯 **Model Integration**
### **Using the HasTranslations Trait**
```php
// Add to your Venue model
use App\Models\Traits\HasTranslations;
class Venue extends Model
{
use HasTranslations;
// Now you can use:
$venue->getName('bg'); // Get name in Bulgarian
$venue->getDescription('en'); // Get description in English
$venue->getFullAddress('bg'); // Get full address in Bulgarian
}
```
### **Automatic Fallback Logic**
```php
// Automatic fallback chain:
// 1. Requested locale (e.g., 'bg')
// 2. Fallback locale (e.g., 'en')
// 3. Any available translation
// 4. Empty string
$venue->getName('fr'); // Falls back to 'en' if 'fr' not available
$venue->getName(); // Uses current app locale
```
### **Translation Status Methods**
```php
$venue->hasTranslation('bg'); // Check if Bulgarian exists
$venue->hasCompleteTranslation('bg'); // Check if Bulgarian is complete
$venue->hasAllRequiredTranslations(); // Check all required translations
$venue->getTranslationCompletionPercentage(); // Get completion percentage
$venue->getMissingLocales(); // Get missing languages
```
---
## 🛠 **Service Layer Usage**
### **VenueTranslationService Methods**
```php
use App\Services\VenueTranslationService;
$service = new VenueTranslationService();
// Get all translations for venue
$translations = $service->getVenueTranslations($venue);
// Save translation
$translation = $service->saveVenueTranslation($venue, 'bg', [
'name' => 'Име на обекта',
'description' => 'Описание...',
]);
// Get translation status
$status = $service->getTranslationStatus($venue);
// Copy translation
$service->copyTranslation($venue, 'en', 'bg');
// Search by content
$venues = $service->searchByTranslatedContent('conference', 'en');
// Get analytics
$analytics = $service->getTranslationAnalytics();
```
---
## 📊 **Analytics & Reporting**
### **Translation Completion Analytics**
```php
$analytics = [
'total_venues' => 150,
'supported_locales' => ['en', 'bg'],
'locale_stats' => [
'en' => [
'complete_count' => 150,
'completion_rate' => 100.0,
],
'bg' => [
'complete_count' => 120,
'completion_rate' => 80.0,
],
],
'completion_stats' => [
'complete' => 120, // All required translations
'partial' => 25, // Some translations
'missing' => 5, // No translations
],
];
```
### **Per-Venue Status**
```php
$status = [
'overall_completion' => 85,
'has_all_required' => false,
'missing_locales' => ['bg'],
'incomplete_translations' => 1,
'locales' => [
'en' => [
'name' => 'English',
'exists' => true,
'complete' => true,
'completion_percentage' => 100,
'last_updated' => '2024-01-15 10:30:00',
],
'bg' => [
'name' => 'Български',
'exists' => true,
'complete' => false,
'completion_percentage' => 70,
'last_updated' => '2024-01-14 15:45:00',
],
],
];
```
---
## 🔍 **Search & Discovery**
### **Multilingual Search**
```php
// Search venues by translated content
$venues = $service->searchByTranslatedContent('conference hall', 'en', [
'city' => 'Sofia',
'country' => 'Bulgaria',
]);
// Results include translated fields
foreach ($venues as $venue) {
echo $venue->getName('en'); // English name
echo $venue->getDescription('en'); // English description
}
```
### **Frontend Integration**
```javascript
// JavaScript search example
async function searchVenues(query, locale = 'en') {
const response = await fetch(`/api/translations/search?query=${query}&locale=${locale}`, {
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json',
},
});
const data = await response.json();
return data.data.venues;
}
```
---
## 📱 **Frontend Display**
### **Displaying Translated Content**
```php
// In Blade templates
<h1>{{ $venue->getName(app()->getLocale()) }}</h1>
<p>{{ $venue->getDescription(app()->getLocale()) }}</p>
<div class="address">
{{ $venue->getFullAddress(app()->getLocale()) }}
</div>
<div class="amenities">
{!! $venue->translation->getFormattedAmenities() !!}
</div>
```
### **Language Switcher**
```blade
@if($venue->getAvailableLocales() > 1)
<div class="language-switcher">
@foreach(config('app.supported_locales') as $locale => $name)
<a href="?locale={{ $locale }}"
class="{{ app()->getLocale() === $locale ? 'active' : '' }}">
{{ $name }}
</a>
@endforeach
</div>
@endif
```
---
## 🔄 **Import/Export**
### **Export Translations**
```bash
curl -X GET "https://your-domain.com/api/venues/1/translations/export" \
-H "Authorization: Bearer {token}"
```
### **Import Translations**
```bash
curl -X POST "https://your-domain.com/api/venues/1/translations/import" \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"translations": {
"en": {
"name": "Venue Name",
"description": "English description..."
},
"bg": {
"name": "Име на обекта",
"description": "Българско описание..."
}
}
}'
```
---
## 🛡️ **Security & Permissions**
### **Role-Based Access**
- **Admin** - Full access to all venues and analytics
- **Venue Owner** - Access only to their own venues
- **User** - Read-only access to public venue information
### **Authorization Checks**
```php
// In controller methods
$this->authorize('view', $venue); // Check if user can view venue
$this->authorize('update', $venue); // Check if user can update venue
```
---
## 🎯 **Best Practices**
### **For Venue Owners**
1. **Start with English** - Create complete English translation first
2. **Use Copy Feature** - Copy English to other languages as starting point
3. **Professional Translation** - Use professional translators for quality
4. **Regular Updates** - Keep all languages synchronized
5. **SEO Optimization** - Provide meta titles and descriptions for each language
### **For Developers**
1. **Use Service Layer** - Access translations through VenueTranslationService
2. **Handle Fallbacks** - Always account for missing translations
3. **Validate Input** - Use provided validation rules
4. **Log Changes** - Track translation updates for audit
5. **Cache Results** - Cache frequently accessed translations
### **Content Guidelines**
1. **Consistent Branding** - Maintain brand voice across languages
2. **Cultural Adaptation** - Adapt content for cultural relevance
3. **SEO Keywords** - Include relevant keywords in each language
4. **Character Limits** - Respect field length limitations
5. **Formatting** - Use consistent formatting across translations
---
## 🚨 **Troubleshooting**
### **Common Issues**
```php
// Issue: Translation not found
$translation = $venue->translation('bg');
if (!$translation) {
// Handle missing translation
return $venue->translationOrFallback();
}
// Issue: Incomplete translation
if (!$venue->hasCompleteTranslation('bg')) {
// Show completion status
$status = $venue->getTranslationStatus();
}
// Issue: API validation errors
try {
$translation = $service->saveVenueTranslation($venue, 'bg', $data);
} catch (ValidationException $e) {
return response()->json(['errors' => $e->errors()], 422);
}
```
### **Debug Commands**
```bash
# Check migration status
php artisan migrate:status
# Test translation service
php artisan tinker
>>> $venue = Venue::find(1);
>>> $venue->getTranslationStatus();
>>> $venue->getName('bg');
```
---
## 📈 **Performance Optimization**
### **Database Optimization**
- **Indexes** - Proper indexes on venue_id, locale, and name fields
- **Eager Loading** - Load translations with venues when needed
- **Caching** - Cache frequently accessed translations
### **API Optimization**
- **Pagination** - Use pagination for large result sets
- **Selective Fields** - Only request needed fields
- **Compression** - Enable gzip compression for API responses
---
## 🎉 **Benefits**
### **For Venue Owners**
- **Global Reach** - Reach customers in their native language
- **Better SEO** - Improved search rankings in multiple languages
- **Professional Image** - Show commitment to international customers
- **Easy Management** - Simple interface for managing translations
### **For Customers**
- **Native Language** - Browse venues in preferred language
- **Better Understanding** - Clear information in familiar language
- **Trust Building** - Professional multilingual presence builds trust
- **Improved Experience** - Seamless booking experience in native language
### **For Business**
- **Market Expansion** - Easy entry into new markets
- **Competitive Advantage** - Stand out with multilingual support
- **Customer Satisfaction** - Higher satisfaction with native language support
- **Analytics** - Detailed insights into translation usage
---
**This comprehensive venue translation system provides everything needed for professional multilingual venue management, from database structure to admin interface and API integration!** 🌍✨