0
# Django-Rosetta
1

2
A Django application that facilitates the translation process of your Django projects by providing a web-based interface for managing gettext catalogs. Django-Rosetta enables translators to edit .po files directly through a browser without requiring technical knowledge of gettext tools, offering translation suggestions, access control, and seamless integration with Django's internationalization framework.
3

4
## Package Information
5

6
- **Package Name**: django-rosetta
7
- **Language**: Python
8
- **Framework**: Django 4.2+
9
- **Installation**: `pip install django-rosetta`
10

11
## Core Imports
12

13
```python
14
# Add to Django settings
15
INSTALLED_APPS = [
16
    # ... other apps
17
    'rosetta',
18
]
19

20
# URL configuration
21
from django.urls import include, path
22
urlpatterns = [
23
    path('rosetta/', include('rosetta.urls')),
24
]
25
```
26

27
Common programmatic usage:
28

29
```python
30
from rosetta import get_version
31
from rosetta.access import can_translate
32
from rosetta.conf import settings as rosetta_settings
33
from rosetta.poutil import find_pos
34
from rosetta.signals import entry_changed, post_save
35
from rosetta.storage import get_storage
36
from rosetta.translate_utils import translate, TranslationException
37
```
38

39
## Basic Usage
40

41
```python
42
# In your Django project settings.py
43
INSTALLED_APPS = [
44
    'django.contrib.admin',
45
    'django.contrib.auth',
46
    'django.contrib.contenttypes',
47
    'django.contrib.sessions',
48
    'django.contrib.messages',
49
    'django.contrib.staticfiles',
50
    'rosetta',  # Add this
51
    # ... your other apps
52
]
53

54
# URL configuration in urls.py
55
from django.contrib import admin
56
from django.urls import path, include
57

58
urlpatterns = [
59
    path('admin/', admin.site.urls),
60
    path('rosetta/', include('rosetta.urls')),
61
    # ... your other URLs
62
]
63

64
# Optional: Configure Rosetta settings
65
ROSETTA_MESSAGES_PER_PAGE = 10
66
ROSETTA_ENABLE_TRANSLATION_SUGGESTIONS = True
67
ROSETTA_SHOW_AT_ADMIN_PANEL = True
68
```
69

70
After setup, navigate to `/rosetta/` in your Django application to access the translation interface. The application will automatically discover .po files in your project and present them for editing.
71

72
## Architecture
73

74
Django-Rosetta is built around Django's standard application architecture with specialized components:
75

76
- **Views**: Web interface for translation management with pagination, filtering, and AJAX support
77
- **Storage Backends**: Pluggable data persistence (session, cache, or dummy storage)
78
- **Access Control**: Configurable permission system for translation access
79
- **Translation Services**: Integration with external APIs (DeepL, Google, Azure, OpenAI)
80
- **Signals**: Django signals for extensibility and workflow integration
81
- **Template System**: Custom template tags and filters for the web interface
82

83
The application maintains database independence by not creating any database tables, storing working data in configurable backends (session or cache by default).
84

85
## Capabilities
86

87
### Web Interface and Views
88

89
Core web interface providing browser-based translation editing, file management, pagination, and download functionality for .po/.mo files.
90

91
```python { .api }
92
class TranslationFileListView(RosettaBaseMixin, TemplateView):
93
    """Lists available translation files for editing."""
94

95
class TranslationFormView(RosettaFileLevelMixin, TemplateView):
96
    """Main translation editing interface with pagination."""
97

98
class TranslationFileDownload(RosettaFileLevelMixin, View):
99
    """Handles .po/.mo file downloads."""
100

101
def translate_text(request):
102
    """AJAX endpoint for translation suggestions."""
103
```
104

105
[Web Interface](./web-interface.md)
106

107
### Access Control and Permissions
108

109
Configurable permission system controlling who can access translation features, with support for user groups, language-specific permissions, and custom access control functions.
110

111
```python { .api }
112
def can_translate(user) -> bool:
113
    """Check if user can access Rosetta translation interface."""
114

115
def can_translate_language(user, langid: str) -> bool:
116
    """Check if user can translate specific language."""
117

118
def get_access_control_function():
119
    """Get configured access control predicate function."""
120
```
121

122
[Access Control](./access-control.md)
123

124
### Configuration Management
125

126
Comprehensive settings system for customizing translation behavior, API integrations, storage backends, and user interface options.
127

128
```python { .api }
129
class RosettaSettings:
130
    """Central configuration management for all Rosetta settings."""
131
    
132
# Global settings instance
133
settings: RosettaSettings
134

135
def reload_settings(*args, **kwargs):
136
    """Signal handler for settings changes."""
137
```
138

139
[Configuration](./configuration.md)
140

141
### Translation Services Integration
142

143
Integration with external translation APIs providing automatic translation suggestions to assist translators.
144

145
```python { .api }
146
def translate(text: str, from_language: str, to_language: str) -> str:
147
    """Main translation function supporting multiple services."""
148

149
class TranslationException(Exception):
150
    """Exception raised by translation services."""
151

152
def translate_by_deepl(text: str, to_language: str, auth_key: str) -> str:
153
def translate_by_google(text: str, input_language: str, output_language: str, credentials_path: str, project_id: str) -> str:
154
def translate_by_azure(text: str, from_language: str, to_language: str, subscription_key: str) -> str:
155
def translate_by_openai(text: str, from_language: str, to_language: str, api_key: str) -> str:
156
```
157

158
[Translation Services](./translation-services.md)
159

160
### Storage Backends
161

162
Pluggable storage system for persisting translation work-in-progress data, supporting session-based, cache-based, or custom storage implementations.
163

164
```python { .api }
165
class BaseRosettaStorage:
166
    """Abstract base class for storage backends."""
167

168
class SessionRosettaStorage(BaseRosettaStorage):
169
    """Session-based storage backend."""
170

171
class CacheRosettaStorage(BaseRosettaStorage):
172
    """Cache-based storage backend (default)."""
173

174
def get_storage(request) -> BaseRosettaStorage:
175
    """Get configured storage instance for request."""
176
```
177

178
[Storage Backends](./storage-backends.md)
179

180
### File Operations and Utilities
181

182
Utilities for discovering, processing, and managing .po/.mo translation files across Django projects.
183

184
```python { .api }
185
def find_pos(lang: str, project_apps: bool = True, django_apps: bool = False, third_party_apps: bool = False) -> list:
186
    """Find .po files for specified language across application types."""
187

188
def timestamp_with_timezone(dt=None) -> str:
189
    """Generate timestamp with timezone information."""
190

191
def pagination_range(first: int, last: int, current: int) -> list:
192
    """Generate pagination ranges for UI."""
193
```
194

195
[File Operations](./file-operations.md)
196

197
### Template Integration
198

199
Django template tags and filters for integrating Rosetta functionality into custom templates and extending the web interface.
200

201
```python { .api }
202
# Template filters
203
def can_translate(user) -> bool
204
def format_message(message: str) -> str
205
def lines_count(message: str) -> int
206
def is_fuzzy(entry) -> bool
207

208
# Template tags  
209
class IncrNode(template.Node):
210
    """Counter increment tag implementation."""
211
```
212

213
[Template Integration](./template-integration.md)
214

215
### Django Signals
216

217
Event system for extending Rosetta functionality and integrating with custom workflows through Django's signal framework.
218

219
```python { .api }
220
entry_changed = django.dispatch.Signal()
221
"""
222
Fired when translation entry is modified.
223
Provides: user, old_msgstr, old_fuzzy, pofile, language_code
224
"""
225

226
post_save = django.dispatch.Signal()  
227
"""
228
Fired after .po file is saved.
229
Provides: language_code, request
230
"""
231
```
232

233
[Django Signals](./django-signals.md)
234

235
## Types
236

237
```python { .api }
238
# Version information
239
VERSION: tuple[int, int, int]  # (0, 10, 2)
240

241
def get_version(limit: int = 3) -> str:
242
    """Return the version as a human-format string."""
243

244
# Django app configuration
245
class RosettaAppConfig(AppConfig):
246
    """Django application configuration with admin panel integration."""
247
    name: str = "rosetta"
248
    def ready(self) -> None: ...
249
```