Django-Translatable-Fields/example/README.md

# Django Translatable Fields - Examples

This directory contains comprehensive examples demonstrating all features of django-translatable-fields.

## Files Overview

- **`models.py`** - Example models showcasing all translatable field types
- **`admin.py`** - Admin configurations for the example models
- **`usage_examples.py`** - Practical usage examples and demonstrations

## Example Models

### 1. Product Model
Demonstrates basic translatable fields:
- `CharField` - Product name
- `TextField` - Product description  
- `SlugField` - SEO-friendly URL slug
- `EmailField` - Support contact email
- `URLField` - Product website URL

### 2. Category Model
Shows category organization with translations:
- `CharField` - Category name
- `TextField` - Category description
- `SlugField` - URL-friendly category slug
- `CharField` - SEO meta description

### 3. BlogPost Model
Comprehensive example with all field types:
- `CharField` - Blog post title and meta description
- `TextField` - Main blog post content
- `SlugField` - URL slug for the post
- `EmailField` - Author contact email
- `URLField` - External reference URL

### 4. Company Model
Business-focused model with contact information:
- `CharField` - Company name
- `TextField` - Company description and address
- `SlugField` - Company URL slug
- `EmailField` - Main contact email
- `URLField` - Company website

## Running the Examples

### 1. Django Shell Usage

```python
# Start Django shell
python manage.py shell

# Import and run examples
from example.usage_examples import run_all_examples
run_all_examples()
```

### 2. Individual Example Functions

```python
from example.usage_examples import (
    create_sample_data,
    demonstrate_language_switching,
    demonstrate_direct_access,
    demonstrate_translation_methods,
    demonstrate_all_field_types
)

# Create sample data
product, blog_post, company = create_sample_data()

# Try different demonstrations
demonstrate_language_switching()
demonstrate_direct_access()
demonstrate_translation_methods()
demonstrate_all_field_types()
```

## Usage Patterns Demonstrated

### 1. Language-Aware Access
```python
from django.utils.translation import activate

# Fields automatically return values based on current language
activate('en')
print(product.name)  # "Awesome Widget"

activate('de') 
print(product.name)  # "Fantastisches Widget"
```

### 2. Direct Language Access
```python
# Access specific language directly
print(product.name_en)  # "Awesome Widget"
print(product.name_de)  # "Fantastisches Widget"
print(product.name_fr)  # "Widget Fantastique"
```

### 3. Translation Management
```python
# Get all translations for a field
translations = product.get_all_translations('name')
# {'en': 'Awesome Widget', 'de': 'Fantastisches Widget', 'fr': 'Widget Fantastique'}

# Get specific translation
german_name = product.get_translation('name', 'de')

# Set translation programmatically
product.set_translation('name', 'es', 'Widget Fantástico')
product.save()
```

### 4. All Field Types in Action
The examples demonstrate proper usage of:
- **CharField** - Text fields with max_length
- **TextField** - Longer text content
- **SlugField** - URL-friendly identifiers
- **EmailField** - Email addresses with validation
- **URLField** - Web URLs with validation

## Admin Interface Features

The admin examples show:
- Clean interface with translate buttons
- Modal overlays for translation management
- WYSIWYG editor for TextField content
- Proper field validation per language
- Drag and resize functionality for modals

## Field Validation

Each field type includes proper validation:
- **EmailField** - Valid email format per language
- **URLField** - Valid URL format per language  
- **SlugField** - Slug format validation per language
- **CharField/TextField** - Length and content validation

## Integration with Django Features

Examples demonstrate compatibility with:
- Django admin interface
- Model forms and validation
- Django's internationalization system
- Search functionality
- List filters and display options
- Prepopulated fields (for slugs)

## Best Practices Shown

1. **Model Design** - Proper use of translatable vs non-translatable fields
2. **Admin Configuration** - Clean, user-friendly admin interfaces
3. **Data Access** - Efficient translation retrieval and management
4. **Validation** - Proper field validation across languages
5. **SEO Optimization** - Language-specific slugs and meta descriptions

## Testing Your Implementation

Use these examples to:
1. Verify all field types work correctly
2. Test language switching functionality
3. Validate admin interface behavior
4. Check translation storage and retrieval
5. Ensure proper field validation

The examples provide a solid foundation for implementing translatable fields in your own Django applications.