Audience: WordPress site admins who embed the tracker on a page, plus translators who use the dashboard. Prerequisites: No PHP knowledge required. You need write access to the WordPress admin and (for issue maintenance) a GitHub account.
The Translation Tracker is a dashboard for the translation progress of the WordPress learning content on learn.wordpress.org and in the Training Handbook. On a WordPress page it shows which content is already translated, which is currently being worked on, and which is still open. Per content item you see the status of each component (text, subtitles, quiz, video, etc.) and who is working on it.
The data does not come from the WordPress site itself but from a GitHub Action that refreshes a JSON file every 12 hours. The plugin reads this file once per cache cycle and renders the overview from it. This separation keeps the site fast and the plugin lean.
Three parts of the overall system:
| Component | Where? | What? |
|---|---|---|
| GitHub issues | WordPress/Learn repo, DACH project board |
Translators maintain the status per item |
| GitHub Action | Training-Translation-Tracker |
Builds tracker.json every 12 h |
| WordPress plugin | This site | Reads the JSON, renders the dashboard |
You mostly work with the GitHub issues (maintaining status) and see the result in the dashboard.
| WordPress | 6.0 or higher |
| PHP | 8.0 or higher |
| Internet access | The site must be able to reach raw.githubusercontent.com |
- Download the ZIP, get the current
training-translation-tracker.zipfrom the Releases tab of the GitHub repo. - In the WP admin, click Plugins → Add New.
- Click Upload Plugin at the top, then pick the ZIP file.
- Click Install Now.
- After a successful upload, click Activate Plugin.
If an older version is already installed, first deactivate and delete the old version (red "Delete" action in the plugin list). Only then upload the new ZIP. Settings and cache are preserved.
After installation, the plugin list contains an entry "Training Translation Tracker" with a version number. In the Settings menu there is a new submenu "Translation Tracker".
Available at WP Admin → Settings → Translation Tracker.
The address from which the plugin loads the JSON file. By default it points at the data branch of the inventory plugin repo:
https://raw.githubusercontent.com/rfluethi/Training-Translation-Tracker/data/tracker.json
Only change this URL if the action repo moves or if a different data source should be used. In 99 % of cases it stays at the default.
How long the loaded JSON sits in the WordPress transient cache before it is reloaded. Default is 12 hours, matching the 12 h cadence of the action.
Set it shorter (e.g. 1 hour) during test phases or when fast updates are needed. Set it longer (e.g. 24 hours) when the data source is stable and HTTP traffic should be minimized.
Allowed range: 1 to 168 hours (up to one week).
Forces a fresh fetch on the next page load. Useful when an update has just been pushed on GitHub and you want to see it immediately without waiting for the cache to expire.
Shows the generated_at timestamp from the current cache. From this you see when the action last built the currently cached state. If the date is older than expected, the cache is stale, either press "Clear cache" or trigger the action manually (see section 6).
Directly below the settings fields the plugin lists shortcode examples with "Copy" buttons. This lets you grab common variants without retyping them from this document.
In the WordPress editor (Gutenberg, Classic or Page Builder):
-
Open or create a page where the dashboard should appear. Usual title: "Translation Tracker".
-
Insert a Shortcode block (in Gutenberg: "/" → "Shortcode").
-
Write into the block content:
[translation_tracker] -
Save and publish the page.
-
Open the page (preview or live URL). The dashboard appears where the shortcode sits.
Page builders (Elementor, Divi, etc.) also have a shortcode block or a text widget that runs shortcodes. Insert [translation_tracker] there.
Attributes control what the dashboard shows. Several can be combined:
| Attribute | Values | Effect |
|---|---|---|
pathway |
Slug of a pathway, multiple separated by comma | Shows only the named learning paths |
show_pathways |
yes/no |
Show or hide all pathway groups (default yes) |
show_orphans |
yes/no |
Show or hide "Other (outside scope)" |
show_handbook |
yes/no |
Show or hide the Training Handbook group |
show_stats |
yes/no |
Show or hide the stats header at the top |
When pathway is set, the plugin automatically hides orphan and handbook groups (assumed intent: "I only want this pathway overview"). If you still want them, explicitly add show_orphans="yes".
When pathway is not set, orphan and handbook groups are shown by default.
The pathway attribute accepts several spellings for the same pathway:
- Short slug:
pathway="user" - Full label slug:
pathway="beginner-wordpress-user" - Original label:
pathway="Beginner WordPress User"
All three match the same pathway group. Case is ignored.
Complete overview:
[translation_tracker]
One page per pathway:
[translation_tracker pathway="user"]
[translation_tracker pathway="lesson-plans"]
Multiple pathways:
[translation_tracker pathway="user, contributor"]
Hide stats (you have your own header):
[translation_tracker show_stats="no"]
Only the Training Handbook:
[translation_tracker show_pathways="no" show_orphans="no"]
A pathway plus handbook, no orphans:
[translation_tracker pathway="user" show_handbook="yes" show_orphans="no"]
The explicit show_handbook="yes" overrides the smart default.
Show the totals per status:
- Items, all items combined
- done (green),
overall_status = done - Review (gold),
overall_status = review - in progress (blue),
overall_status = wip - open (yellow),
overall_status = open. Yellow since 0.4.4 to make "still to do" items stand out. - unspecified (neutral gray), sub-count of items whose every component is still
unset(the status table in the issue has not been filled in yet). Sub-count of "open" — these items are also counted in the "open" pill, this pill surfaces "how many of the open ones are completely untouched". - n/a (light gray),
overall_status = na
Clicking a pill filters the cards to that status. Clicking "Items" resets the filter. The "n/a" pill is informational only and not clickable.
Below the search field, two grouped dropdowns let you filter by component AND component status together. Example use case: "show me all cards where the text component is still open" — pick text in the first dropdown and open in the second.
The second dropdown is disabled while the first one is on "All components", because a status filter without a chosen component would not be useful.
When the first dropdown is set to "All components" no component filter is applied. Picking a specific component without a status shows cards that have that component (regardless of its status). Picking both narrows further.
Filter selections are persisted in the browser (localStorage) so they survive page reloads.
Each card shows one content item:
Status bar on the left in the color of overall_status.
Original column (left): title and link to the English content. If there is a WordPress.tv recording or a YouTube video, they appear as small links below the title.
Translation column (right): same for the German translation. If the English title is shown there in gray italics, the German translation does not exist yet.
Footer row: left side shows the issue number (e.g. #2952) linked to the GitHub issue, next to it the issue status open/closed and possibly markers ("Orphan", "Duplicate", "Original draft", "Out of scope"). Right side shows up to seven small colored icons for the components (thumbnails, text, subtitles, exercise, quiz, audio, video). Hovering over an icon opens a popover with status, creator + avatar and reviewer + avatar.
Live search in the header. Typing filters the cards whose title (German or English) or issue number contains the entered text.
Click the title of a section (e.g. "Get Started With WordPress") to collapse the cards below it. The arrow turns from ▾ to ▸. Click again to expand. The state is stored in the browser, so on the next page load it stays as last left.
Three ways:
The GitHub Action runs on a cron schedule and publishes a new tracker.json. The plugin reloads it at the latest when the cache duration has expired (default 12 h).
In the plugin settings, press the button. On the next page load the plugin fetches fresh data, provided the action has rebuilt in the meantime.
Whoever has write access to the action repo can trigger the workflow "Build tracker.json" manually via the GitHub web UI. After that:
- Wait about 2 minutes until the action has finished.
- Press "Clear cache now" in the plugin.
- Reload the page.
The full template is in Issue-Templates-DACH.md. The key points here:
In the WordPress/Learn repo, not in the inventory plugin repo. The issue must be on the DACH project board with the custom field Locale = German.
-
Canonical original URL,
https://, lowercase, trailing slash, no query/fragment, nowww..Correct:
https://learn.wordpress.org/lesson/wordpress-essentials-domains-and-hosting/Incorrect:
http://learn.wordpress.org/lesson/WordPress-Essentialsor…?ref=email -
Locale marking on the DACH project board (
Locale = German). -
Status table with HTML markers, a Markdown table between
<!-- TRANSLATION-STATUS-START -->and<!-- TRANSLATION-STATUS-END -->. Copy the template verbatim.
open · wip · review · done · na
A sixth value unset exists internally and is assigned by the action to
components when an issue has no parsed status table yet (e.g. the
template was not filled in). You normally do not write unset yourself;
the action emits it automatically so the frontend can render those
components in a neutral gray rather than the bright yellow "open" color.
GitHub username, with or without the @ prefix. Both rfluethi and @rfluethi work, the parser strips the leading @ automatically. Separate multiple names with a comma. Leave empty if nobody is assigned yet.
If two issues are created for the same URL by mistake, the tracker shows both with a warning icon "multiple issues". Cleanup is manual, close one or repurpose it.
Causes: the JSON file has never been loaded successfully, which happens the very first time, before the first action run. Or the JSON URL in the settings is wrong or unreachable. Or the site has no internet access to raw.githubusercontent.com.
Fix: check the URL in the plugin settings and press "Clear cache". If still empty, ask a site admin to check the action repo.
The cache has not expired yet. Either wait or press "Clear cache".
Check the issue number on the DACH GitHub project, does the issue exist at all? The issue must have the label Locale=German. The original URL in the issue must match the inventory URL exactly (lowercase, with trailing slash, without query parameters). If all of that is correct, the next action run picks it up and the item appears on the next cache update.
Orphan: the issue points to a URL that no longer exists in the inventory (learn.wordpress.org) (renamed, deleted).
Out of scope: the issue is valid, but the URL is not in the action's scope.yml, a deliberate choice of which content lands on the dashboard.
In both cases action is needed either on the issue (fix the URL) or on the scope (add the item to scope.yml, see developer docs).
In certain theme / page builder combinations the interaction JavaScript does not load reliably. Workaround: instead of clicking filters, use a shortcode with a pathway= attribute on its own page, that filters server-side and always works.
Diagnosis: open the browser console (F12 → Console + Network) and check whether tracker.js loaded with HTTP 200. If not, the page builder stripped the <script src> tag out of the output.
The component popover shows GitHub avatars for creator and reviewer, fetched directly from https://avatars.githubusercontent.com/. If your site uses a strict Content-Security-Policy (CSP), this host must be on the img-src allow-list, otherwise the browser blocks the requests and the popover shows initials only.
Recommended CSP additions if you have one:
img-src 'self' data: https://avatars.githubusercontent.com;
Sites without a custom CSP do not need to do anything.
Before you report a bug, please note down:
- Plugin version (shown in the plugin list and in the settings).
- WordPress version and, if relevant, page builder / theme.
- Which shortcode the page uses.
- What you expected and what actually happened.
- Screenshot of the page, preferably full browser window.
- Browser console (F12 → Console tab), copy all red errors.
Open an issue in the action repo: https://github.com/rfluethi/Training-Translation-Tracker/issues
Or contact the maintainer directly by email (see the plugin header).
- System architecture: Architecture.md
- Operations (releases, token, recovery): Operations.md
- Code & extensions: Developer.md