wagtail-sidebyside 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. wagtail_sidebyside-0.1.0/.gitignore +10 -0
  2. wagtail_sidebyside-0.1.0/CHANGELOG.md +11 -0
  3. wagtail_sidebyside-0.1.0/LICENSE +21 -0
  4. wagtail_sidebyside-0.1.0/PKG-INFO +270 -0
  5. wagtail_sidebyside-0.1.0/README.md +243 -0
  6. wagtail_sidebyside-0.1.0/pyproject.toml +63 -0
  7. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/__init__.py +0 -0
  8. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/action_menu.py +57 -0
  9. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/apps.py +13 -0
  10. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/conf.py +16 -0
  11. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/fields.py +406 -0
  12. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/forms.py +170 -0
  13. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/locale/fr/LC_MESSAGES/django.mo +0 -0
  14. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/locale/fr/LC_MESSAGES/django.po +637 -0
  15. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/locale/nl/LC_MESSAGES/django.mo +0 -0
  16. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/locale/nl/LC_MESSAGES/django.po +633 -0
  17. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/management/__init__.py +0 -0
  18. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/management/commands/__init__.py +0 -0
  19. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/management/commands/import_localize_drafts.py +64 -0
  20. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/managers.py +35 -0
  21. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/migrations/0001_initial.py +40 -0
  22. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/migrations/0002_translationsettings.py +53 -0
  23. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/migrations/0003_drop_wagtail_localize.py +11 -0
  24. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/migrations/0004_removed_translations.py +17 -0
  25. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/migrations/0005_instructions_help_text.py +21 -0
  26. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/migrations/0006_ai_usage.py +46 -0
  27. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/migrations/0007_awaiting_source.py +17 -0
  28. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/migrations/__init__.py +0 -0
  29. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/models.py +103 -0
  30. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/panels.py +24 -0
  31. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/signals.py +16 -0
  32. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/static/sidebyside/sidebyside.css +533 -0
  33. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/static/sidebyside/translate.js +143 -0
  34. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/templates/sidebyside/create.html +22 -0
  35. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/templates/sidebyside/dashboard_panel.html +21 -0
  36. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/templates/sidebyside/includes/object_preview.html +11 -0
  37. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/templates/sidebyside/includes/translation_bar.html +27 -0
  38. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/templates/sidebyside/includes/translation_bar_button.html +7 -0
  39. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/templates/sidebyside/overview.html +47 -0
  40. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/templates/sidebyside/panels/machine_translation_status.html +3 -0
  41. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/templates/sidebyside/translate.html +236 -0
  42. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/templates/sidebyside/translators/claude_status.html +64 -0
  43. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/templates/sidebyside/translators/status.html +9 -0
  44. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/templates/sidebyside/translators/usage.html +32 -0
  45. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/templates/wagtailadmin/pages/edit.html +12 -0
  46. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/templates/wagtailadmin/pages/explorable_index.html +12 -0
  47. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/templatetags/__init__.py +0 -0
  48. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/templatetags/sidebyside_tags.py +64 -0
  49. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/translators/__init__.py +68 -0
  50. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/translators/claude.py +233 -0
  51. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/use_cases/__init__.py +0 -0
  52. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/use_cases/machine_translate.py +86 -0
  53. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/use_cases/page_status.py +99 -0
  54. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/use_cases/sync_tree.py +83 -0
  55. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/use_cases/translate_page.py +359 -0
  56. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/views.py +323 -0
  57. wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/wagtail_hooks.py +161 -0
  58. wagtail_sidebyside-0.1.0/tests/__init__.py +0 -0
  59. wagtail_sidebyside-0.1.0/tests/demo.py +102 -0
  60. wagtail_sidebyside-0.1.0/tests/demo_settings.py +8 -0
  61. wagtail_sidebyside-0.1.0/tests/demo_translator.py +21 -0
  62. wagtail_sidebyside-0.1.0/tests/settings.py +87 -0
  63. wagtail_sidebyside-0.1.0/tests/test_extension.py +85 -0
  64. wagtail_sidebyside-0.1.0/tests/test_translate.py +1238 -0
  65. wagtail_sidebyside-0.1.0/tests/testapp/__init__.py +0 -0
  66. wagtail_sidebyside-0.1.0/tests/testapp/apps.py +6 -0
  67. wagtail_sidebyside-0.1.0/tests/testapp/migrations/0001_initial.py +107 -0
  68. wagtail_sidebyside-0.1.0/tests/testapp/migrations/__init__.py +0 -0
  69. wagtail_sidebyside-0.1.0/tests/testapp/models.py +60 -0
  70. wagtail_sidebyside-0.1.0/tests/testapp/templates/testapp/chart_block.html +1 -0
  71. wagtail_sidebyside-0.1.0/tests/testapp/templates/testapp/test_page.html +17 -0
  72. wagtail_sidebyside-0.1.0/tests/urls.py +10 -0
@@ -0,0 +1,10 @@
1
+ __pycache__/
2
+ *.pyc
3
+ .venv/
4
+ dist/
5
+ build/
6
+ *.egg-info/
7
+ .pytest_cache/
8
+ .ruff_cache/
9
+ tests/demo.sqlite3
10
+ tests/media/
@@ -0,0 +1,11 @@
1
+ # Changelog
2
+
3
+ ## 0.1.0 (2026-11-17)
4
+
5
+ First release.
6
+
7
+ - Side-by-side translation screen, tree sync, live preview.
8
+ - Machine translation with Claude (optional extra `claude`), pluggable backends.
9
+ - Hooks: `sidebyside_block_kind`, `sidebyside_construct_rows`,
10
+ `sidebyside_before_save_translation`, `sidebyside_after_save_translation`.
11
+ - `import_localize_drafts` command for moving from wagtail-localize.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 PythonUnited
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,270 @@
1
+ Metadata-Version: 2.5
2
+ Name: wagtail-sidebyside
3
+ Version: 0.1.0
4
+ Summary: Translate Wagtail pages side by side: one main language, translations next to the source, optional AI.
5
+ Project-URL: Homepage, https://github.com/PythonUnited/wagtail-sidebyside
6
+ Project-URL: Issues, https://github.com/PythonUnited/wagtail-sidebyside/issues
7
+ Project-URL: Changelog, https://github.com/PythonUnited/wagtail-sidebyside/blob/main/CHANGELOG.md
8
+ Author: PythonUnited
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Environment :: Web Environment
13
+ Classifier: Framework :: Django
14
+ Classifier: Framework :: Wagtail
15
+ Classifier: Intended Audience :: Developers
16
+ Classifier: Operating System :: OS Independent
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Programming Language :: Python :: 3.14
21
+ Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
22
+ Requires-Python: >=3.12
23
+ Requires-Dist: wagtail<9,>=8.1
24
+ Provides-Extra: claude
25
+ Requires-Dist: anthropic>=2.9; extra == 'claude'
26
+ Description-Content-Type: text/markdown
27
+
28
+ # wagtail-sidebyside
29
+
30
+ > **Why this exists:** we built it because the existing translation solutions
31
+ > for Wagtail were simply not good enough for us. Editors translated one string
32
+ > at a time without seeing the page, saving and publishing were separate from
33
+ > Wagtail's own flow, So we made the editor we wanted: the whole page,
34
+ > side by side, one save.
35
+ >
36
+ > **Made with Claude:** this package was designed and written together with
37
+ > [Claude Opus 5.5](https://www.anthropic.com/claude) (Anthropic), in Claude
38
+ > Code, by a developer at [PythonUnited](https://github.com/PythonUnited).
39
+
40
+ Translate Wagtail pages side by side. One main language, every other language
41
+ is a translation of it. The editor sees the source next to the translation,
42
+ field by field, and saves or publishes the whole page at once. Optional machine
43
+ translation with AI.
44
+
45
+ ![Translating a page: source on the left, translation on the right](https://raw.githubusercontent.com/PythonUnited/wagtail-sidebyside/main/docs/screenshots/translate.png)
46
+
47
+ - **Side by side**: every text of the page in one screen, including StreamField
48
+ blocks, the slug and the SEO fields, in the order of the editor.
49
+ - **One save**: "Save draft" and "Publish" for the whole translation, with
50
+ Wagtail's own action menu, revisions, history and live preview.
51
+ - **Knows what changed**: every field is *to do*, *done*, *outdated* (with a
52
+ word diff of the source change) or *to review* (AI or reused text).
53
+ - **Tree in sync**: new source pages get their translations; moving,
54
+ unpublishing and deleting cascade. A translation is never published ahead of
55
+ its source.
56
+ - **AI** (optional): translate one field or all empty fields with Claude, with a
57
+ glossary, house style instructions and a monthly budget.
58
+ - **Built on Wagtail core i18n** (`Locale`, `TranslatableMixin`): no extra
59
+ translation tables, no monkey patching. Extend it with hooks.
60
+
61
+ | The source page | All translations |
62
+ | --- | --- |
63
+ | ![Translation bar on the source page](https://raw.githubusercontent.com/PythonUnited/wagtail-sidebyside/main/docs/screenshots/source.png) | ![Overview of all pages and their translation status](https://raw.githubusercontent.com/PythonUnited/wagtail-sidebyside/main/docs/screenshots/overview.png) |
64
+
65
+ Live preview while translating:
66
+
67
+ ![Live preview of the translation](https://raw.githubusercontent.com/PythonUnited/wagtail-sidebyside/main/docs/screenshots/preview.png)
68
+
69
+ ## Requirements
70
+
71
+ Python 3.12+, Wagtail 8.1+.
72
+
73
+ ## Install
74
+
75
+ ```bash
76
+ pip install wagtail-sidebyside # without machine translation
77
+ pip install "wagtail-sidebyside[claude]" # with machine translation by Claude
78
+ ```
79
+
80
+ ```python
81
+ INSTALLED_APPS = [
82
+ "wagtail_sidebyside", # before wagtail.admin: it extends the page editor
83
+ # ...
84
+ "wagtail.contrib.settings",
85
+ "wagtail.locales",
86
+ "wagtail.admin",
87
+ "wagtail",
88
+ # ...
89
+ ]
90
+
91
+ WAGTAIL_I18N_ENABLED = True
92
+ WAGTAIL_CONTENT_LANGUAGES = LANGUAGES = [("fr", "Francais"), ("en", "English")]
93
+
94
+ SIDEBYSIDE = {
95
+ "SOURCE_LOCALE": "fr", # the main language; default: Wagtail's default locale
96
+ }
97
+ ```
98
+
99
+ ```bash
100
+ python manage.py migrate
101
+ ```
102
+
103
+ Add the locales under Settings > Locales. New source pages get their
104
+ translations right away; for existing pages the translation bar above the page
105
+ has a button to create them. Editors find all work under **Translations** in
106
+ the menu.
107
+
108
+ ## Settings
109
+
110
+ All in the `SIDEBYSIDE` dict:
111
+
112
+ | Key | Default | |
113
+ | --- | --- | --- |
114
+ | `SOURCE_LOCALE` | Wagtail's default locale | Language code of the main language. |
115
+ | `TRANSLATOR` | `"wagtail_sidebyside.translators.claude.ClaudeTranslator"` | Machine translation backend, see below. |
116
+ | `AI_PROVIDER` | `""` (off) | Claude: `"anthropic"` or `"foundry"` (Microsoft Foundry / Azure). |
117
+ | `AI_MODEL` | `"claude-opus-5-5"` | Claude model. |
118
+ | `AI_PRICES` | built in | `{model: (input, output)}` in USD per million tokens, for the cost estimate. |
119
+
120
+ Fields that are the same in every language (an image, a colour) go in the page
121
+ model:
122
+
123
+ ```python
124
+ class BlogPage(Page):
125
+ translation_exclude = ["header_image"]
126
+ ```
127
+
128
+ Choice fields and blocks without text are copied from the source anyway.
129
+
130
+ ## Machine translation
131
+
132
+ With Claude directly, create a key at [platform.claude.com](https://platform.claude.com)
133
+ (tip: in a workspace with a spend limit) and put it in the server's
134
+ environment, not in a settings file:
135
+
136
+ ```bash
137
+ ANTHROPIC_API_KEY=sk-ant-api...
138
+ ```
139
+
140
+ ```python
141
+ SIDEBYSIDE = {"SOURCE_LOCALE": "fr", "AI_PROVIDER": "anthropic"}
142
+ ```
143
+
144
+ Through Microsoft Foundry: `"AI_PROVIDER": "foundry"` with
145
+ `ANTHROPIC_FOUNDRY_API_KEY` and `ANTHROPIC_FOUNDRY_RESOURCE`.
146
+
147
+ Editors manage the rest in **Settings > Translations**: switch AI on or off,
148
+ a monthly budget (the AI buttons hide when it is reached), a glossary
149
+ (`fromage = cheese`) and instructions for tone and style. The page also shows
150
+ this month's usage and a "Test connection" button.
151
+
152
+ AI never saves by itself: a machine translation is marked *to review* until an
153
+ editor saves it.
154
+
155
+ ## Extending
156
+
157
+ ### Another translation service
158
+
159
+ Subclass `Translator` and point `SIDEBYSIDE["TRANSLATOR"]` at it:
160
+
161
+ ```python
162
+ from wagtail_sidebyside.translators import TranslationError, Translator, Usage
163
+
164
+
165
+ class DeepLTranslator(Translator):
166
+ def available(self):
167
+ return bool(os.environ.get("DEEPL_KEY"))
168
+
169
+ def translate(self, items, source, target, glossary="", instructions=""):
170
+ # items: [(text, is_html), ...]; source/target: language names
171
+ texts = ... # call the service, raise TranslationError on failure
172
+ return texts, Usage(input_tokens=..., output_tokens=...)
173
+ ```
174
+
175
+ Optional: `status()` and `status_template` for the settings screen, `check()`
176
+ for "Test connection", `cost(usage)` for the budget.
177
+
178
+ ### Hooks
179
+
180
+ Standard [Wagtail hooks](https://docs.wagtail.org/en/stable/reference/hooks.html),
181
+ in your app's `wagtail_hooks.py`:
182
+
183
+ ```python
184
+ from wagtail import hooks
185
+
186
+
187
+ @hooks.register("sidebyside_block_kind")
188
+ def block_kind(block):
189
+ """How a leaf block is translated: "text", "textarea", "richtext",
190
+ "html", "image", "document", False (not translatable) or None (default)."""
191
+ if isinstance(block, MapBlock):
192
+ return False
193
+
194
+
195
+ @hooks.register("sidebyside_construct_rows")
196
+ def construct_rows(rows, source, target):
197
+ """Change the rows of the translation screen in place."""
198
+ rows[:] = [row for row in rows if row.unit.path != "seo_title"]
199
+
200
+
201
+ @hooks.register("sidebyside_before_save_translation")
202
+ def before_save(request, source_page, target_page):
203
+ """Return a response to stop the save."""
204
+
205
+
206
+ @hooks.register("sidebyside_after_save_translation")
207
+ def after_save(request, source_page, target_page, revision):
208
+ """Return a response to replace the redirect."""
209
+ ```
210
+
211
+ ## Coming from wagtail-localize
212
+
213
+ Both use Wagtail core i18n, so pages and their translations stay as they are.
214
+ wagtail-sidebyside treats the translated text already on the pages as done.
215
+ One catch: wagtail-localize only writes a translation into the page when it is
216
+ published. Translations that were entered but never published live only in
217
+ wagtail-localize's own tables. Step 1 saves those as drafts before
218
+ wagtail-localize goes. On a live site, deploy step 1 and step 2 separately.
219
+
220
+ **Step 1: install next to wagtail-localize**
221
+
222
+ ```python
223
+ INSTALLED_APPS = [
224
+ "wagtail_sidebyside", # before wagtail.admin
225
+ "wagtail_localize", # stays for now
226
+ "wagtail.locales", # instead of "wagtail_localize.locales"
227
+ "wagtail.contrib.settings",
228
+ # ...
229
+ ]
230
+ ```
231
+
232
+ ```bash
233
+ pip install "wagtail-sidebyside[claude]"
234
+ python manage.py migrate
235
+ python manage.py import_localize_drafts --dry-run # lists the waiting translations
236
+ python manage.py import_localize_drafts # saves them as drafts
237
+ ```
238
+
239
+ Live pages are not changed; the drafts show up in the side-by-side screen
240
+ as work to finish.
241
+
242
+ **Step 2: remove wagtail-localize**
243
+
244
+ ```bash
245
+ python manage.py migrate wagtail_localize zero # drops its tables
246
+ ```
247
+
248
+ Then:
249
+
250
+ - remove `"wagtail_localize"` (and `"wagtail_localize.modeladmin"` if used)
251
+ from `INSTALLED_APPS`;
252
+ - remove `wagtail-localize` from your requirements;
253
+ - remove `translatable_fields` and the `wagtail_localize` imports from your
254
+ models. Fields that were a `SynchronizedField` (the same in every language)
255
+ go in `translation_exclude`;
256
+ - remove any templates or code that use `wagtail_localize`.
257
+
258
+ ## Development
259
+
260
+ ```bash
261
+ uv sync
262
+ uv run pytest
263
+ uv run python -m tests.demo # demo site on http://localhost:8000/cms/ (admin/admin)
264
+ ```
265
+
266
+ The demo uses a fake translator, so no API key is needed.
267
+
268
+ ## License
269
+
270
+ MIT, see [LICENSE](LICENSE).
@@ -0,0 +1,243 @@
1
+ # wagtail-sidebyside
2
+
3
+ > **Why this exists:** we built it because the existing translation solutions
4
+ > for Wagtail were simply not good enough for us. Editors translated one string
5
+ > at a time without seeing the page, saving and publishing were separate from
6
+ > Wagtail's own flow, So we made the editor we wanted: the whole page,
7
+ > side by side, one save.
8
+ >
9
+ > **Made with Claude:** this package was designed and written together with
10
+ > [Claude Opus 5.5](https://www.anthropic.com/claude) (Anthropic), in Claude
11
+ > Code, by a developer at [PythonUnited](https://github.com/PythonUnited).
12
+
13
+ Translate Wagtail pages side by side. One main language, every other language
14
+ is a translation of it. The editor sees the source next to the translation,
15
+ field by field, and saves or publishes the whole page at once. Optional machine
16
+ translation with AI.
17
+
18
+ ![Translating a page: source on the left, translation on the right](https://raw.githubusercontent.com/PythonUnited/wagtail-sidebyside/main/docs/screenshots/translate.png)
19
+
20
+ - **Side by side**: every text of the page in one screen, including StreamField
21
+ blocks, the slug and the SEO fields, in the order of the editor.
22
+ - **One save**: "Save draft" and "Publish" for the whole translation, with
23
+ Wagtail's own action menu, revisions, history and live preview.
24
+ - **Knows what changed**: every field is *to do*, *done*, *outdated* (with a
25
+ word diff of the source change) or *to review* (AI or reused text).
26
+ - **Tree in sync**: new source pages get their translations; moving,
27
+ unpublishing and deleting cascade. A translation is never published ahead of
28
+ its source.
29
+ - **AI** (optional): translate one field or all empty fields with Claude, with a
30
+ glossary, house style instructions and a monthly budget.
31
+ - **Built on Wagtail core i18n** (`Locale`, `TranslatableMixin`): no extra
32
+ translation tables, no monkey patching. Extend it with hooks.
33
+
34
+ | The source page | All translations |
35
+ | --- | --- |
36
+ | ![Translation bar on the source page](https://raw.githubusercontent.com/PythonUnited/wagtail-sidebyside/main/docs/screenshots/source.png) | ![Overview of all pages and their translation status](https://raw.githubusercontent.com/PythonUnited/wagtail-sidebyside/main/docs/screenshots/overview.png) |
37
+
38
+ Live preview while translating:
39
+
40
+ ![Live preview of the translation](https://raw.githubusercontent.com/PythonUnited/wagtail-sidebyside/main/docs/screenshots/preview.png)
41
+
42
+ ## Requirements
43
+
44
+ Python 3.12+, Wagtail 8.1+.
45
+
46
+ ## Install
47
+
48
+ ```bash
49
+ pip install wagtail-sidebyside # without machine translation
50
+ pip install "wagtail-sidebyside[claude]" # with machine translation by Claude
51
+ ```
52
+
53
+ ```python
54
+ INSTALLED_APPS = [
55
+ "wagtail_sidebyside", # before wagtail.admin: it extends the page editor
56
+ # ...
57
+ "wagtail.contrib.settings",
58
+ "wagtail.locales",
59
+ "wagtail.admin",
60
+ "wagtail",
61
+ # ...
62
+ ]
63
+
64
+ WAGTAIL_I18N_ENABLED = True
65
+ WAGTAIL_CONTENT_LANGUAGES = LANGUAGES = [("fr", "Francais"), ("en", "English")]
66
+
67
+ SIDEBYSIDE = {
68
+ "SOURCE_LOCALE": "fr", # the main language; default: Wagtail's default locale
69
+ }
70
+ ```
71
+
72
+ ```bash
73
+ python manage.py migrate
74
+ ```
75
+
76
+ Add the locales under Settings > Locales. New source pages get their
77
+ translations right away; for existing pages the translation bar above the page
78
+ has a button to create them. Editors find all work under **Translations** in
79
+ the menu.
80
+
81
+ ## Settings
82
+
83
+ All in the `SIDEBYSIDE` dict:
84
+
85
+ | Key | Default | |
86
+ | --- | --- | --- |
87
+ | `SOURCE_LOCALE` | Wagtail's default locale | Language code of the main language. |
88
+ | `TRANSLATOR` | `"wagtail_sidebyside.translators.claude.ClaudeTranslator"` | Machine translation backend, see below. |
89
+ | `AI_PROVIDER` | `""` (off) | Claude: `"anthropic"` or `"foundry"` (Microsoft Foundry / Azure). |
90
+ | `AI_MODEL` | `"claude-opus-5-5"` | Claude model. |
91
+ | `AI_PRICES` | built in | `{model: (input, output)}` in USD per million tokens, for the cost estimate. |
92
+
93
+ Fields that are the same in every language (an image, a colour) go in the page
94
+ model:
95
+
96
+ ```python
97
+ class BlogPage(Page):
98
+ translation_exclude = ["header_image"]
99
+ ```
100
+
101
+ Choice fields and blocks without text are copied from the source anyway.
102
+
103
+ ## Machine translation
104
+
105
+ With Claude directly, create a key at [platform.claude.com](https://platform.claude.com)
106
+ (tip: in a workspace with a spend limit) and put it in the server's
107
+ environment, not in a settings file:
108
+
109
+ ```bash
110
+ ANTHROPIC_API_KEY=sk-ant-api...
111
+ ```
112
+
113
+ ```python
114
+ SIDEBYSIDE = {"SOURCE_LOCALE": "fr", "AI_PROVIDER": "anthropic"}
115
+ ```
116
+
117
+ Through Microsoft Foundry: `"AI_PROVIDER": "foundry"` with
118
+ `ANTHROPIC_FOUNDRY_API_KEY` and `ANTHROPIC_FOUNDRY_RESOURCE`.
119
+
120
+ Editors manage the rest in **Settings > Translations**: switch AI on or off,
121
+ a monthly budget (the AI buttons hide when it is reached), a glossary
122
+ (`fromage = cheese`) and instructions for tone and style. The page also shows
123
+ this month's usage and a "Test connection" button.
124
+
125
+ AI never saves by itself: a machine translation is marked *to review* until an
126
+ editor saves it.
127
+
128
+ ## Extending
129
+
130
+ ### Another translation service
131
+
132
+ Subclass `Translator` and point `SIDEBYSIDE["TRANSLATOR"]` at it:
133
+
134
+ ```python
135
+ from wagtail_sidebyside.translators import TranslationError, Translator, Usage
136
+
137
+
138
+ class DeepLTranslator(Translator):
139
+ def available(self):
140
+ return bool(os.environ.get("DEEPL_KEY"))
141
+
142
+ def translate(self, items, source, target, glossary="", instructions=""):
143
+ # items: [(text, is_html), ...]; source/target: language names
144
+ texts = ... # call the service, raise TranslationError on failure
145
+ return texts, Usage(input_tokens=..., output_tokens=...)
146
+ ```
147
+
148
+ Optional: `status()` and `status_template` for the settings screen, `check()`
149
+ for "Test connection", `cost(usage)` for the budget.
150
+
151
+ ### Hooks
152
+
153
+ Standard [Wagtail hooks](https://docs.wagtail.org/en/stable/reference/hooks.html),
154
+ in your app's `wagtail_hooks.py`:
155
+
156
+ ```python
157
+ from wagtail import hooks
158
+
159
+
160
+ @hooks.register("sidebyside_block_kind")
161
+ def block_kind(block):
162
+ """How a leaf block is translated: "text", "textarea", "richtext",
163
+ "html", "image", "document", False (not translatable) or None (default)."""
164
+ if isinstance(block, MapBlock):
165
+ return False
166
+
167
+
168
+ @hooks.register("sidebyside_construct_rows")
169
+ def construct_rows(rows, source, target):
170
+ """Change the rows of the translation screen in place."""
171
+ rows[:] = [row for row in rows if row.unit.path != "seo_title"]
172
+
173
+
174
+ @hooks.register("sidebyside_before_save_translation")
175
+ def before_save(request, source_page, target_page):
176
+ """Return a response to stop the save."""
177
+
178
+
179
+ @hooks.register("sidebyside_after_save_translation")
180
+ def after_save(request, source_page, target_page, revision):
181
+ """Return a response to replace the redirect."""
182
+ ```
183
+
184
+ ## Coming from wagtail-localize
185
+
186
+ Both use Wagtail core i18n, so pages and their translations stay as they are.
187
+ wagtail-sidebyside treats the translated text already on the pages as done.
188
+ One catch: wagtail-localize only writes a translation into the page when it is
189
+ published. Translations that were entered but never published live only in
190
+ wagtail-localize's own tables. Step 1 saves those as drafts before
191
+ wagtail-localize goes. On a live site, deploy step 1 and step 2 separately.
192
+
193
+ **Step 1: install next to wagtail-localize**
194
+
195
+ ```python
196
+ INSTALLED_APPS = [
197
+ "wagtail_sidebyside", # before wagtail.admin
198
+ "wagtail_localize", # stays for now
199
+ "wagtail.locales", # instead of "wagtail_localize.locales"
200
+ "wagtail.contrib.settings",
201
+ # ...
202
+ ]
203
+ ```
204
+
205
+ ```bash
206
+ pip install "wagtail-sidebyside[claude]"
207
+ python manage.py migrate
208
+ python manage.py import_localize_drafts --dry-run # lists the waiting translations
209
+ python manage.py import_localize_drafts # saves them as drafts
210
+ ```
211
+
212
+ Live pages are not changed; the drafts show up in the side-by-side screen
213
+ as work to finish.
214
+
215
+ **Step 2: remove wagtail-localize**
216
+
217
+ ```bash
218
+ python manage.py migrate wagtail_localize zero # drops its tables
219
+ ```
220
+
221
+ Then:
222
+
223
+ - remove `"wagtail_localize"` (and `"wagtail_localize.modeladmin"` if used)
224
+ from `INSTALLED_APPS`;
225
+ - remove `wagtail-localize` from your requirements;
226
+ - remove `translatable_fields` and the `wagtail_localize` imports from your
227
+ models. Fields that were a `SynchronizedField` (the same in every language)
228
+ go in `translation_exclude`;
229
+ - remove any templates or code that use `wagtail_localize`.
230
+
231
+ ## Development
232
+
233
+ ```bash
234
+ uv sync
235
+ uv run pytest
236
+ uv run python -m tests.demo # demo site on http://localhost:8000/cms/ (admin/admin)
237
+ ```
238
+
239
+ The demo uses a fake translator, so no API key is needed.
240
+
241
+ ## License
242
+
243
+ MIT, see [LICENSE](LICENSE).
@@ -0,0 +1,63 @@
1
+ [build-system]
2
+ requires = ["hatchling"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "wagtail-sidebyside"
7
+ version = "0.1.0"
8
+ description = "Translate Wagtail pages side by side: one main language, translations next to the source, optional AI."
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ license-files = ["LICENSE"]
12
+ authors = [{ name = "PythonUnited" }]
13
+ requires-python = ">=3.12"
14
+ dependencies = ["wagtail>=8.1,<9"]
15
+ classifiers = [
16
+ "Development Status :: 4 - Beta",
17
+ "Environment :: Web Environment",
18
+ "Framework :: Django",
19
+ "Framework :: Wagtail",
20
+ "Intended Audience :: Developers",
21
+ "Operating System :: OS Independent",
22
+ "Programming Language :: Python :: 3",
23
+ "Programming Language :: Python :: 3.12",
24
+ "Programming Language :: Python :: 3.13",
25
+ "Programming Language :: Python :: 3.14",
26
+ "Topic :: Internet :: WWW/HTTP :: Site Management",
27
+ ]
28
+
29
+ [project.optional-dependencies]
30
+ claude = ["anthropic>=2.9"]
31
+
32
+ [project.urls]
33
+ Homepage = "https://github.com/PythonUnited/wagtail-sidebyside"
34
+ Issues = "https://github.com/PythonUnited/wagtail-sidebyside/issues"
35
+ Changelog = "https://github.com/PythonUnited/wagtail-sidebyside/blob/main/CHANGELOG.md"
36
+
37
+ [dependency-groups]
38
+ dev = [
39
+ "anthropic>=2.9",
40
+ "pytest>=9",
41
+ "pytest-django>=4.14",
42
+ "ruff>=0.17",
43
+ ]
44
+
45
+ [tool.hatch.build.targets.wheel]
46
+ packages = ["src/wagtail_sidebyside"]
47
+
48
+ [tool.hatch.build.targets.sdist]
49
+ include = ["src", "tests", "README.md", "CHANGELOG.md", "LICENSE"]
50
+
51
+ [tool.pytest.ini_options]
52
+ DJANGO_SETTINGS_MODULE = "tests.settings"
53
+ pythonpath = ["."]
54
+ testpaths = ["tests"]
55
+ addopts = ["--strict-markers"]
56
+
57
+ [tool.ruff]
58
+ line-length = 88
59
+ src = ["src", "tests"]
60
+
61
+ [tool.ruff.lint]
62
+ select = ["E", "F", "I", "UP", "B"]
63
+ ignore = ["E501"]
@@ -0,0 +1,57 @@
1
+ """Footer actions of the translation screen, on top of Wagtail's own."""
2
+
3
+ from django.utils.translation import gettext_lazy as _
4
+ from wagtail.admin.action_menu import (
5
+ ActionMenuItem,
6
+ CancelWorkflowMenuItem,
7
+ PublishMenuItem,
8
+ RestartWorkflowMenuItem,
9
+ SubmitForModerationMenuItem,
10
+ WorkflowMenuItem,
11
+ )
12
+
13
+
14
+ class PublishTogetherMenuItem(ActionMenuItem):
15
+ """Publish the source's draft and the translation at once."""
16
+
17
+ name = "action-publish-together"
18
+ label = _("Publish source and translation")
19
+ icon_name = "upload"
20
+
21
+
22
+ class PublishTranslationOnlyMenuItem(PublishMenuItem):
23
+ label = _("Publish translation only")
24
+
25
+
26
+ def adapt(action_menu, source_page, user):
27
+ """Workflow actions are left out: the translation screen does not handle
28
+ moderation, so they would only save a draft. When the source has
29
+ unpublished changes, "Publish" publishes the translation only (against
30
+ the published source), with "Publish source and translation" just above
31
+ it. A source that was never published can only be published together
32
+ with its translation."""
33
+ items = action_menu.menu_items
34
+ items[:] = [
35
+ item
36
+ for item in items
37
+ if not isinstance(
38
+ item,
39
+ (
40
+ SubmitForModerationMenuItem,
41
+ WorkflowMenuItem,
42
+ RestartWorkflowMenuItem,
43
+ CancelWorkflowMenuItem,
44
+ ),
45
+ )
46
+ ]
47
+ if not source_page.has_unpublished_changes:
48
+ return
49
+ for index, item in enumerate(items):
50
+ if isinstance(item, PublishMenuItem):
51
+ if source_page.live:
52
+ items[index] = PublishTranslationOnlyMenuItem(order=item.order)
53
+ else:
54
+ del items[index]
55
+ if source_page.permissions_for_user(user).can_publish():
56
+ items.insert(index, PublishTogetherMenuItem())
57
+ return