0
# Web Interface and Views
1

2
Core web interface providing browser-based translation editing, file management, pagination, and download functionality for .po/.mo files. The interface integrates with Django's admin system and provides a user-friendly translation experience.
3

4
## Capabilities
5

6
### Base View Mixins
7

8
Foundation classes providing common functionality for authentication, filtering, and .po file handling.
9

10
```python { .api }
11
class RosettaBaseMixin:
12
    """
13
    Base mixin providing authentication and po_filter property.
14
    
15
    Requires user to pass can_translate() check and provides never_cache decorator.
16
    """
17
    
18
    @property
19
    def po_filter(self) -> dict:
20
        """Filter parameters for .po file selection."""
21

22
class RosettaFileLevelMixin(RosettaBaseMixin):
23
    """
24
    Mixin for operations on single .po files.
25
    
26
    Extends RosettaBaseMixin with file-specific functionality.
27
    """
28
```
29

30
### Translation File Listing
31

32
View for displaying available translation files organized by language and application, with filtering and navigation capabilities.
33

34
```python { .api }
35
class TranslationFileListView(RosettaBaseMixin, TemplateView):
36
    """
37
    Lists available translation files for editing.
38
    
39
    Displays .po files grouped by language and application, with counts
40
    of translated, untranslated, and fuzzy entries. Provides navigation
41
    to translation editing interface.
42
    """
43
    
44
    template_name: str = "rosetta/languages.html"
45
```
46

47
### Translation Editing Interface
48

49
Main interface for editing translation entries with pagination, search, filtering, and inline editing capabilities.
50

51
```python { .api }
52
class TranslationFormView(RosettaFileLevelMixin, TemplateView):
53
    """
54
    Main translation editing interface.
55
    
56
    Provides paginated view of translation entries with:
57
    - Inline editing of msgstr values
58
    - Fuzzy flag management  
59
    - Search and filtering
60
    - Progress tracking
61
    - Batch operations
62
    """
63
    
64
    template_name: str = "rosetta/pofile.html"
65
```
66

67
### File Download
68

69
Handles downloading of .po and .mo files for offline editing or distribution.
70

71
```python { .api }
72
class TranslationFileDownload(RosettaFileLevelMixin, View):
73
    """
74
    Handles .po/.mo file downloads.
75
    
76
    Supports downloading:
77
    - Original .po files
78
    - Compiled .mo files  
79
    - Modified .po files with current translations
80
    """
81
    
82
    def get(self, request, *args, **kwargs) -> HttpResponse:
83
        """
84
        Download translation file.
85
        
86
        Parameters:
87
        - file_format: 'po' or 'mo'
88
        
89
        Returns:
90
        HttpResponse with file attachment
91
        """
92
```
93

94
### Translation Suggestions API
95

96
AJAX endpoint providing automatic translation suggestions from configured external services.
97

98
```python { .api }
99
def translate_text(request) -> JsonResponse:
100
    """
101
    AJAX endpoint for translation suggestions.
102
    
103
    Accepts POST request with:
104
    - text: Text to translate
105
    - from_language: Source language code
106
    - to_language: Target language code
107
    
108
    Returns:
109
    JsonResponse with translated text or error message
110
    
111
    Requires:
112
    - User authentication via can_translate()
113
    - ROSETTA_ENABLE_TRANSLATION_SUGGESTIONS = True
114
    - Configured translation service API keys
115
    """
116
```
117

118
### URL Configuration
119

120
URL patterns defining the routing for all Rosetta views and endpoints.
121

122
```python { .api }
123
urlpatterns: list = [
124
    # Main interfaces
125
    path('', TranslationFileListView.as_view(), name='rosetta-file-list'),
126
    path('files/<path:po_filter>/', TranslationFormView.as_view(), name='rosetta-form'),
127
    
128
    # File operations
129
    path('download/<path:po_filter>/', TranslationFileDownload.as_view(), name='rosetta-download-file'),
130
    
131
    # API endpoints
132
    path('translate/', translate_text, name='rosetta.translate_text'),
133
    
134
    # Legacy redirects
135
    path('select/', RedirectView.as_view(), name='rosetta-old-home-redirect'),
136
    path('files/', RedirectView.as_view(), name='rosetta-file-list-redirect'),
137
]
138
```
139

140
### Utility Functions
141

142
Helper functions supporting the web interface functionality.
143

144
```python { .api }
145
def get_app_name(path: str) -> str:
146
    """
147
    Extract Django application name from .po file path.
148
    
149
    Parameters:
150
    - path: File system path to .po file
151
    
152
    Returns:
153
    Application name string
154
    """
155

156
def urlencode_safe(query: dict) -> str:
157
    """
158
    URL-encode query parameters safely for template use.
159
    
160
    Parameters:
161
    - query: Dictionary of query parameters
162
    
163
    Returns:
164
    URL-encoded query string
165
    """
166

167
class LoginURL(Promise):
168
    """
169
    Tests-friendly login URL that resolves at runtime.
170
    
171
    Used by user_passes_test decorator to provide dynamic
172
    login URL based on ROSETTA_LOGIN_URL setting.
173
    """
174
    
175
    def __str__(self) -> str:
176
        """Returns configured login URL."""
177
```
178

179
## Usage Examples
180

181
### Basic View Integration
182

183
```python
184
# In your Django URLs configuration
185
from django.urls import path, include
186

187
urlpatterns = [
188
    path('rosetta/', include('rosetta.urls')),
189
]
190

191
# Access the interface at /rosetta/ in your browser
192
# - Lists all available translation files
193
# - Click on a file to start editing translations
194
# - Use pagination to navigate through entries
195
# - Download .po/.mo files as needed
196
```
197

198
### Custom View Extension
199

200
```python
201
from rosetta.views import RosettaBaseMixin, TranslationFormView
202

203
class CustomTranslationView(RosettaBaseMixin, TemplateView):
204
    """Custom view extending Rosetta functionality."""
205
    
206
    template_name = 'my_app/custom_translations.html'
207
    
208
    def get_context_data(self, **kwargs):
209
        context = super().get_context_data(**kwargs)
210
        # Add custom context
211
        context['custom_data'] = self.get_custom_data()
212
        return context
213
        
214
    def get_custom_data(self):
215
        """Add your custom logic here."""
216
        return {}
217
```
218

219
### AJAX Translation Integration
220

221
```javascript
222
// Frontend JavaScript for translation suggestions
223
function getTranslationSuggestion(text, fromLang, toLang) {
224
    fetch('/rosetta/translate/', {
225
        method: 'POST',
226
        headers: {
227
            'Content-Type': 'application/x-www-form-urlencoded',
228
            'X-CSRFToken': getCookie('csrftoken')
229
        },
230
        body: new URLSearchParams({
231
            'text': text,
232
            'from_language': fromLang,
233
            'to_language': toLang
234
        })
235
    })
236
    .then(response => response.json())
237
    .then(data => {
238
        if (data.translation) {
239
            // Use the translation suggestion
240
            document.getElementById('msgstr-field').value = data.translation;
241
        }
242
    });
243
}
244
```