0
# Configuration Management
1

2
Comprehensive settings system for customizing translation behavior, API integrations, storage backends, and user interface options. The configuration system provides centralized management of all Rosetta features with sensible defaults and extensive customization options.
3

4
## Capabilities
5

6
### Settings Management
7

8
Central configuration class managing all Rosetta settings with validation and default values.
9

10
```python { .api }
11
class RosettaSettings:
12
    """
13
    Central configuration management for all Rosetta settings.
14
    
15
    Provides access to all configuration options with proper defaults,
16
    validation, and runtime reloading capability.
17
    """
18
    
19
    def __getattr__(self, name: str):
20
        """Get setting value with validation and defaults."""
21
    
22
    def reload(self) -> None:
23
        """Reload settings from Django configuration."""
24

25
# Global settings instance  
26
settings: RosettaSettings
27
"""
28
Global settings instance providing access to all Rosetta configuration.
29
Import as: from rosetta.conf import settings as rosetta_settings
30
"""
31

32
def reload_settings(*args, **kwargs) -> None:
33
    """
34
    Signal handler for settings changes.
35
    
36
    Connected to Django's setting_changed signal to automatically
37
    reload Rosetta settings when Django settings are modified.
38
    """
39
```
40

41
## Core Configuration Options
42

43
### Interface and Pagination Settings
44

45
```python { .api }
46
ROSETTA_MESSAGES_PER_PAGE: int = 10
47
"""Number of translation entries to display per page."""
48

49
ROSETTA_SHOW_AT_ADMIN_PANEL: bool = True  
50
"""Whether to show Rosetta link in Django admin panel."""
51

52
ROSETTA_SHOW_OCCURRENCES: bool = True
53
"""Whether to display message occurrences in source code."""
54

55
ROSETTA_ENABLE_REFLANG: bool = True
56
"""Whether to enable reference language display."""
57
```
58

59
### Translation Services Configuration
60

61
```python { .api }
62
ROSETTA_ENABLE_TRANSLATION_SUGGESTIONS: bool = False
63
"""Enable automatic translation suggestions from external APIs."""
64

65
# DeepL API Configuration
66
ROSETTA_DEEPL_AUTH_KEY: str = ''
67
"""DeepL API authentication key for translation suggestions."""
68

69
ROSETTA_DEEPL_LANGUAGES: list = ['EN', 'DE', 'FR', 'IT', 'JA', 'ES', 'NL', 'PL', 'PT', 'RU', 'ZH']
70
"""List of language codes supported by DeepL API."""
71

72
# Google Translate Configuration  
73
ROSETTA_GOOGLE_APPLICATION_CREDENTIALS_PATH: str = ''
74
"""Path to Google Cloud service account credentials JSON file."""
75

76
ROSETTA_GOOGLE_PROJECT_ID: str = ''
77
"""Google Cloud project ID for translation API."""
78

79
# Azure Translator Configuration
80
ROSETTA_AZURE_CLIENT_SECRET: str = ''
81
"""Azure Translator API subscription key."""
82

83
# OpenAI Configuration
84
ROSETTA_OPENAI_API_KEY: str = ''
85
"""OpenAI API key for translation suggestions."""
86

87
ROSETTA_OPENAI_PROMPT_TEMPLATE: str = 'Translate the following text from {from_language} to {to_language}: {text}'
88
"""Template for OpenAI translation prompts."""
89

90
# Legacy Yandex (deprecated)
91
ROSETTA_YANDEX_TRANSLATE_KEY: str = ''
92
"""Yandex Translate API key (deprecated)."""
93
```
94

95
### Language and Localization Settings
96

97
```python { .api }
98
ROSETTA_MAIN_LANGUAGE: str = settings.LANGUAGE_CODE
99
"""Main language code for the project."""
100

101
ROSETTA_MESSAGES_SOURCE_LANGUAGE_CODE: str = ROSETTA_MAIN_LANGUAGE  
102
"""Source language code for translation messages."""
103

104
ROSETTA_MESSAGES_SOURCE_LANGUAGE_NAME: str = 'English'
105
"""Display name for the source language."""
106

107
ROSETTA_LANGUAGES: list = []
108
"""
109
List of languages available for translation.
110
If empty, uses all languages from Django's LANGUAGES setting.
111
"""
112

113
ROSETTA_LANGUAGE_GROUPS: dict = {}
114
"""
115
Language-specific user group permissions.
116
Format: {'language_code': ['group1', 'group2']}
117
"""
118
```
119

120
### File Processing Settings
121

122
```python { .api }
123
ROSETTA_EXCLUDED_APPLICATIONS: list = []
124
"""List of Django applications to exclude from translation scanning."""
125

126
ROSETTA_EXCLUDED_PATHS: list = []
127
"""List of file paths to exclude from .po file discovery."""
128

129
ROSETTA_POFILENAMES: tuple = ('django.po', 'djangojs.po')
130
"""Tuple of allowed .po filename patterns."""
131

132
ROSETTA_POFILE_WRAP_WIDTH: int = 78
133
"""Line wrap width for .po file formatting."""
134

135
ROSETTA_AUTO_COMPILE: bool = True
136
"""Whether to automatically compile .mo files after .po file changes."""
137
```
138

139
### Storage and Caching Settings
140

141
```python { .api }
142
ROSETTA_STORAGE_CLASS: str = 'rosetta.storage.CacheRosettaStorage'
143
"""Full Python path to storage backend class."""
144

145
ROSETTA_CACHE_NAME: str = 'default'
146
"""Name of Django cache backend to use for storage."""
147
```
148

149
### Access Control Settings
150

151
```python { .api }
152
ROSETTA_REQUIRES_AUTH: bool = True
153
"""Whether authentication is required for Rosetta access."""
154

155
ROSETTA_ACCESS_CONTROL_FUNCTION: str = 'rosetta.access.is_superuser_staff_or_in_translators_group'
156
"""Full Python path to access control function."""
157

158
ROSETTA_LOGIN_URL: str = '/admin/login/'
159
"""URL to redirect users for authentication."""
160
```
161

162
### Server Integration Settings
163

164
```python { .api }
165
ROSETTA_WSGI_AUTO_RELOAD: bool = False
166
"""Whether to auto-reload WSGI server when .po files change."""
167

168
ROSETTA_UWSGI_AUTO_RELOAD: bool = False  
169
"""Whether to auto-reload uWSGI server when .po files change."""
170
```
171

172
## Usage Examples
173

174
### Basic Configuration
175

176
```python
177
# settings.py - Basic Rosetta setup
178
INSTALLED_APPS = [
179
    'rosetta',
180
]
181

182
# Increase entries per page
183
ROSETTA_MESSAGES_PER_PAGE = 25
184

185
# Show Rosetta in admin panel
186
ROSETTA_SHOW_AT_ADMIN_PANEL = True
187

188
# Enable automatic .mo compilation
189
ROSETTA_AUTO_COMPILE = True
190
```
191

192
### Translation Services Setup
193

194
```python
195
# settings.py - Enable translation suggestions with DeepL
196
ROSETTA_ENABLE_TRANSLATION_SUGGESTIONS = True
197
ROSETTA_DEEPL_AUTH_KEY = 'your-deepl-api-key'
198

199
# Or use Google Translate
200
ROSETTA_GOOGLE_APPLICATION_CREDENTIALS_PATH = '/path/to/credentials.json'
201
ROSETTA_GOOGLE_PROJECT_ID = 'your-google-project-id'
202

203
# Or use OpenAI
204
ROSETTA_OPENAI_API_KEY = 'your-openai-api-key'
205
ROSETTA_OPENAI_PROMPT_TEMPLATE = 'Please translate from {from_language} to {to_language}: {text}'
206

207
# Or use Azure Translator
208
ROSETTA_AZURE_CLIENT_SECRET = 'your-azure-subscription-key'
209
```
210

211
### Advanced Language Configuration
212

213
```python
214
# settings.py - Custom language setup
215
ROSETTA_LANGUAGES = [
216
    ('en', 'English'),
217
    ('fr', 'French'), 
218
    ('de', 'German'),
219
    ('es', 'Spanish'),
220
]
221

222
# Language-specific permissions
223
ROSETTA_LANGUAGE_GROUPS = {
224
    'fr': ['french_translators'],
225
    'de': ['german_translators'],
226
    'es': ['spanish_translators'],
227
}
228

229
# Exclude certain applications
230
ROSETTA_EXCLUDED_APPLICATIONS = ['debug_toolbar', 'django_extensions']
231

232
# Custom .po file names
233
ROSETTA_POFILENAMES = ('django.po', 'djangojs.po', 'custom.po')
234
```
235

236
### Storage Backend Configuration
237

238
```python
239
# settings.py - Use session storage instead of cache
240
ROSETTA_STORAGE_CLASS = 'rosetta.storage.SessionRosettaStorage'
241

242
# Or create custom storage backend
243
class CustomRosettaStorage(BaseRosettaStorage):
244
    """Custom storage implementation."""
245
    
246
    def set(self, key, value):
247
        # Custom storage logic
248
        pass
249
        
250
    def get(self, key, default=None):
251
        # Custom retrieval logic
252
        pass
253

254
ROSETTA_STORAGE_CLASS = 'myapp.storage.CustomRosettaStorage'
255
```
256

257
### Programmatic Settings Access
258

259
```python
260
from rosetta.conf import settings as rosetta_settings
261

262
def my_view(request):
263
    """Access Rosetta settings programmatically."""
264
    
265
    # Check if translation suggestions are enabled
266
    if rosetta_settings.ENABLE_TRANSLATION_SUGGESTIONS:
267
        # Use translation service
268
        pass
269
    
270
    # Get configured messages per page
271
    page_size = rosetta_settings.MESSAGES_PER_PAGE
272
    
273
    # Access any setting
274
    storage_class = rosetta_settings.STORAGE_CLASS
275
    
276
    return render(request, 'template.html', {
277
        'page_size': page_size,
278
        'suggestions_enabled': rosetta_settings.ENABLE_TRANSLATION_SUGGESTIONS,
279
    })
280
```
281

282
### Runtime Settings Reload
283

284
```python
285
from rosetta.conf import settings as rosetta_settings, reload_settings
286
from django.test.utils import override_settings
287

288
# Settings are automatically reloaded when Django settings change
289
with override_settings(ROSETTA_MESSAGES_PER_PAGE=50):
290
    # Rosetta settings automatically reflect the change
291
    assert rosetta_settings.MESSAGES_PER_PAGE == 50
292

293
# Manual reload (rarely needed)
294
reload_settings()
295
```
296

297
### Custom Access Control
298

299
```python
300
# myapp/access.py
301
def custom_access_control(user):
302
    """Custom access control logic."""
303
    if not user.is_authenticated:
304
        return False
305
    
306
    # Custom business logic
307
    return user.profile.can_translate if hasattr(user, 'profile') else False
308

309
# settings.py
310
ROSETTA_ACCESS_CONTROL_FUNCTION = 'myapp.access.custom_access_control'
311
ROSETTA_LOGIN_URL = '/accounts/login/'
312
```