chore: added docs for customizing translations for theme + custom repos#1351
Open
eemaanamir wants to merge 3 commits into
Open
chore: added docs for customizing translations for theme + custom repos#1351eemaanamir wants to merge 3 commits into
eemaanamir wants to merge 3 commits into
Conversation
Abdul-Muqadim-Arbisoft
moved this from Pending Triage
to In review
in Tutor project management
Faraz32123
reviewed
Apr 30, 2026
Contributor
Faraz32123
left a comment
Faraz32123
left a comment
There was a problem hiding this comment.
Can we also add the changelog entry.
Comment on lines
+501
to
+524
| **Step 1 — Pull upstream translations** | ||
|
|
||
| Use Atlas to fetch the latest upstream translations into ``translations-upstream/``:: | ||
|
|
||
| atlas pull translations --output-dir translations-upstream | ||
|
|
||
| This folder is read-only and acts as your baseline. | ||
|
|
||
| **Step 2 — Collect strings from your custom repositories** | ||
|
|
||
| For each forked or new repository, extract translation source strings into ``translations-custom/``. The exact command depends on the repository type: | ||
|
|
||
| - *Python / Django repositories*: ``django-admin makemessages`` or ``i18n_tool extract`` | ||
| - *JavaScript / MFE repositories*: ``npm run i18n:extract`` | ||
|
|
||
| **Step 3 — Isolate your custom strings** | ||
|
|
||
| Compare ``translations-custom/`` against ``translations-upstream/`` and remove any ``msgid`` entries that already exist upstream. This keeps your fork lean and prevents duplicating strings that upstream translators already maintain. | ||
|
|
||
| **Step 4 — Merge into the final output** | ||
|
|
||
| Overlay ``translations-custom/`` on top of ``translations-upstream/`` to produce the ``translations/`` directory. The merge rule is simple: if a ``msgid`` exists in both layers, the custom value wins (as long as it is non-empty); otherwise the upstream value is used. | ||
|
|
||
| For theme repositories (such as a custom Indigo fork), theme translations should be merged into ``edx-platform`` translations rather than kept in a separate locale path, because the platform loads theme strings from its own locale directory at runtime. |
Contributor
There was a problem hiding this comment.
Can we also attach the commands to isolate the translations, Otherwise its just complicating the process and we can simply write that add your custom translations in translations/ folder and its upto the user what process he is following. For example:
- for custom mfe
frontend-app-customadd your translations heretranslations/frontend-app-custom. - For core MFEs e.g.
frontend-app-authoringmfe, add/replace your translations intranslations/frontend-app-authoring. - Same goes for custom plugins
- And for theme, added note would be fine,
For theme repositories (such as a custom Indigo fork), ...
Collaborator
|
Instead of keeping this in configuration, should we make it a tutorial? |
Contributor
Yes, we should move it to tutorial section & add a hyperlink under customizing Translations heading in this same file as well. What do u guys say? |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Issue: overhangio/tutor-indigo#170
Adds documentation explaining how to override theme-level translations (e.g., Indigo) in Tutor, which is not covered in the existing translations section.
This includes:
Additionally, the documentation references the Wikimedia openedx-translations fork as a real-world example of handling translations across custom repositories (platform, MFEs, plugins, and themes).
No changes were made to the existing content — only supplemental documentation was added.