docs: document automated translation updates - #2410
Open
Martin Krzykawski (MartinKrzykawski) wants to merge 2 commits into
Open
docs: document automated translation updates#2410Martin Krzykawski (MartinKrzykawski) wants to merge 2 commits into
Martin Krzykawski (MartinKrzykawski) wants to merge 2 commits into
Conversation
Adds a dedicated article for the two automated halves of the translation workflow that were previously undocumented: - the upstream Crowdin pipeline: how en-GB/de-DE source snippets are collected from shopware/shopware, uploaded to Crowdin, translated and approved by contributors, and downloaded back into shopware/translations including the metadata that installations compare against - the downstream `translation.update` scheduled task: interval, what it does on each run, its requirements, how to inspect, trigger or deactivate it, what it explicitly does not do, and failure handling Cross-links the new page from the built-in translation handling page, the translations index, and the extension points page. Adds the task to the list of default scheduled tasks in the hosting guide and completes the translation section of the command reference. Fixes the command name `snippet:validate` to `translation:validate`.
Developer Docs healthcheckStatus: Completed with |
Contributor
📊 Documentation Impact Analyzer
Reasons
|
Copilot started reviewing on behalf of
Martin Krzykawski (MartinKrzykawski)
July 30, 2026 08:54
View session
Contributor
There was a problem hiding this comment.
Pull request overview
Adds missing documentation for Shopware’s automated translation update workflow, covering both the upstream Crowdin/GitHub Actions pipeline and the downstream translation.update scheduled task in Shopware, and wires this new documentation into existing translation-related pages.
Changes:
- Adds a new concept page describing the end-to-end automated translation update chain (Crowdin ↔
shopware/translations↔ Shopware scheduled task). - Adds/adjusts cross-links across translation docs and scheduled task documentation.
- Completes/aligns the command reference for translation-related CLI commands.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| resources/references/core-reference/commands-reference.md | Adds missing translation CLI commands to the command reference table. |
| guides/hosting/infrastructure/scheduled-task.md | Documents translation.update as a default scheduled task and adds contextual notes/linking. |
| concepts/framework/translations/index.md | Adds the new automated translation updates page to the translations section index. |
| concepts/framework/translations/extension-points.md | Fixes the command name to translation:validate and links to the new automation docs. |
| concepts/framework/translations/built-in-translation-system.md | Cross-links to the new automation page and notes the scheduled task behavior. |
| concepts/framework/translations/automated-translation-updates.md | Introduces the new end-to-end documentation page for automated translation updates. |
Comments suppressed due to low confidence (2)
concepts/framework/translations/automated-translation-updates.md:122
- The docs table guidelines recommend introducing tables with a complete sentence (resources/guidelines/documentation-guidelines/04-fonts-and-formats/01-text.md:105). Consider adding an explicit lead-in before this properties table.
| Property | Value |
concepts/framework/translations/automated-translation-updates.md:195
- Per the documentation table guidelines, table rows should not end sentences with punctuation and tables should be introduced with a complete sentence (resources/guidelines/documentation-guidelines/04-fonts-and-formats/01-text.md:101-106). This troubleshooting table currently has no lead-in sentence, and several cells end sentences with periods.
## Troubleshooting
| Symptom | Cause and solution |
|-------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|
| The task never runs | No background worker is consuming the queue. See [Scheduled Task](../../../guides/hosting/infrastructure/scheduled-task.md). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Martin Krzykawski (MartinKrzykawski)
added
the
added
Fix the link in the scheduled task info box: the "built-in translation system" phrase pointed at the automation page instead of the built-in translation handling page. The automation page is now linked from a separate sentence, so each link text matches its target. Also correct the surrounding grammar in that sentence. Introduce the schedule, task properties, and troubleshooting tables with a lead-in sentence, and drop the sentence-final punctuation from the troubleshooting cells, as required by the table rules in resources/guidelines/documentation-guidelines/04-fonts-and-formats/01-text.md.
Contributor
📊 Documentation Impact Analyzer
Reasons
|
Martin Krzykawski (MartinKrzykawski)
requested a review
from Marcel Brode (marcelbrode)
July 30, 2026 12:44
Marcel Brode (marcelbrode)
requested changes
Jul 30, 2026
|
|
||
| ## Overview | ||
|
|
||
| Translations are not part of a Shopware release. They are maintained in Crowdin, published to the |
Contributor
There was a problem hiding this comment.
Suggested change
| Translations are not part of a Shopware release. They are maintained in Crowdin, published to the | |
| Translations are not part of a Shopware release. They are maintained in Crowdin ([translate.shopware.com](https://translate.shopware.com)), published to the |
Comment on lines
+16
to
+18
| * Upstream, a set of scheduled GitHub Actions workflows exchanges snippets between `shopware/shopware`, Crowdin, and | ||
| the translations repository. | ||
| * Downstream, the `translation.update` scheduled task refreshes the translations that are installed in a shop. |
Contributor
There was a problem hiding this comment.
Suggested change
| * Upstream, a set of scheduled GitHub Actions workflows exchanges snippets between `shopware/shopware`, Crowdin, and | |
| the translations repository. | |
| * Downstream, the `translation.update` scheduled task refreshes the translations that are installed in a shop. | |
| * Upstream: A set of scheduled GitHub Actions workflows exchanges snippets between `shopware/shopware`, Crowdin, and | |
| the translations repository. | |
| * Downstream: The `translation.update` scheduled task refreshes the translations that are installed in a shop. |
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
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.
Summary
Documents the automated part of the translation workflow, which was not covered anywhere so far. New article
concepts/framework/translations/automated-translation-updates.mddescribes both halves of the chain:en-GBsource snippets and thede-DEtranslation are collected fromshopware/shopwareintoshopware/translations, uploaded to Crowdin, translated and approved by contributors, anddownloaded back into a reviewed pull request together with the
crowdin-metadata.jsonupdate. Includes the dailyschedule of the three workflows, the entry point for contributors (translate.shopware.com),
why source strings are changed in code instead of in Crowdin, and the known review pitfalls (snippets containing
HTML, diffs in the source languages).
translation.updatescheduled task — default interval, what it does on each run,its requirements (background worker, outbound HTTPS, private filesystem), how to inspect, trigger, or deactivate it,
what it explicitly does not do (install locales, change the
activeflag, override database snippets, removelanguages), failure handling, and a troubleshooting table.
Supporting adjustments:
built-in-translation-system.md, the translationsindex.md, andextension-points.md.translation.updateadded to the default scheduled tasks inguides/hosting/infrastructure/scheduled-task.md,including the note that it only runs when a translation is installed.
translation:update,translation:list,translation:lint-filenames,translation:validate).snippet:validatetotranslation:validateinextension-points.md.Related links
shopware/translationsworkflowsupdate-translations.yml,crowdin-upload.yml,crowdin-download.ymlChecklist
PageRefreferences where relevant..gitbook.yamlif pages were moved, renamed, or deleted. — not applicable, no page was moved or renamed.wordlist.txt(and sorted it) if spellcheck flags new legitimate terms. — not needed, spellcheck passes unchangedNotes
Two points for the reviewer:
time of writing (the task landed on
6.7.13.x). Please confirm the version before merging.trunkconsumes the translation Admin API endpoints from the Administration yet, so the articledeliberately mentions only the CLI. The Administration part is a follow-up and will be documented together with
that implementation.
Verified locally: markdownlint and the spellcheck (
make spellcheck-local) pass, and all relative links, anchors, andPageReftargets resolve. All statements about the task, the commands, and the pipeline were checked against the codein
shopware/shopwareand the workflows onshopware/translations@main.