Skip to content

fix(docs): six source defects the new translation checks brought to light - #1064

Open
youyongsong wants to merge 2 commits into
masterfrom
fix/docs-defects-found-by-translation-checks
Open

fix(docs): six source defects the new translation checks brought to light#1064
youyongsong wants to merge 2 commits into
masterfrom
fix/docs-defects-found-by-translation-checks

Conversation

@youyongsong

@youyongsong youyongsong commented Aug 25, 2026

Copy link
Copy Markdown
Collaborator

Six defects in the English source, none of which were visible before.

Two were hidden by a lint bug that discarded messages landing on a trailing self-closing component — a canonical API reference page is exactly that shape. Two only showed up once translations started being compared against the source they were made from. The last two were found by a new lint rule, no-unparsed-emphasis, written after a translation produced the same shape of defect.

networking/how_to/kube_ovn/underlay_overlay_st.mdx

The frontmatter has no opening ---:

weight: 13
---

# Automatic Interconnection of Underlay and Overlay Subnets

So weight: 13 was never frontmatter. Markdown reads weight: 13 followed by --- as a setext heading, which means the page renders a second-level heading titled weight: 13 above its own title, and the weight never applies to the sidebar.

Found by comparing heading structure with the translations: the source parsed as 2-1-2-3-2-3-3 where both translations were 1-2-3-2-3-3. It now has a lint rule of its own — no-unopened-frontmatter, which reports this shape without reporting the 88 documents in this repository that legitimately have no frontmatter at all.

developer/s2i/install_builds/install_builds_operator.mdx

One sentence split across two list items:

<ul><li>`Manual`: When a new version is available in the OperatorHub</li><li>the **Upgrade** action will not be executed automatically.</li></ul>

The table therefore reads them as two separate points, the second of which is a sentence fragment. The Russian translation reproduced the split faithfully; the Chinese quietly merged them, which is what surfaced the difference.

apis/advanced_apis/application/query.mdx and management.mdx

Two <OpenAPIPath> paths spell the parameter {cluster}:

/acp/v1/kubernetes/{cluster}/namespaces/{namespace}/applications/{name}
/acp/v1/kubernetes/{cluster}/namespaces/{namespace}/applications/{name}/chartpackage

Every path under applications in the OpenAPI sources spells it {cluster_name} — including the /address path sitting on the very next line of query.mdx. A path that matches nothing renders a blank endpoint section, silently.

developer/quick_start/quick_start_app.mdx and application_workloads/cronjob_create.mdx

Emphasis delimiters that end up printed to the page. **bold** only works when the delimiters sit against the text:

|** Parameter **| **Description** |

The opening run is followed by a space, so it is not an opening delimiter and the header cell reads ** Parameter **. In cronjob_create.mdx a stray closing ** sits after "Failed jobs history limit", where the sibling bullet one line above ends "Successful jobs history limit (default: 20)" with no such marker.

Both are also the source of the same defect in the Russian pages, which reproduced the broken markup faithfully. Changing the English updates their sourceSHA, so the translations are regenerated on the next run and the defect goes with them.


Verified: with these six fixed, doom lint over this repository reports 0 errors — including under the two new rules, which report 5 findings on master as it stands.

The translations are updated to match in auto-translations/container_platform!1.

…light

None of these were visible before. Two were hidden by a lint bug that discarded
messages on a trailing self-closing component; the other two only showed up
because translations are now compared against the source they were made from.

- `networking/how_to/kube_ovn/underlay_overlay_st.mdx` — the frontmatter had no
  opening `---`, so `weight: 13` was not frontmatter at all: it rendered as a
  second-level heading at the top of the page, and the weight never applied.
- `developer/s2i/install_builds/install_builds_operator.mdx` — one sentence was
  split across two list items, so the table read "When a new version is
  available in the OperatorHub" and "the **Upgrade** action will not be executed
  automatically" as two separate points. The Russian translation reproduced the
  split faithfully.
- `apis/advanced_apis/application/query.mdx` and `management.mdx` — two
  `<OpenAPIPath>` paths spell the parameter `{cluster}`, while every OpenAPI
  source spells it `{cluster_name}`. The endpoint sections rendered blank.

The translations are updated to match in
`auto-translations/container_platform!1`.
@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Aug 25, 2026

Copy link
Copy Markdown

Deploying alauda-container-platform with  Cloudflare Pages  Cloudflare Pages

Latest commit: 9246481
Status: ✅  Deploy successful!
Preview URL: https://86ae289c.alauda-container-platform.pages.dev
Branch Preview URL: https://fix-docs-defects-found-by-tr.alauda-container-platform.pages.dev

View logs

`**bold**` only works when the delimiters sit against the text. These two do
not, so readers see the asterisks:

- `developer/quick_start/quick_start_app.mdx` — a table header written
  `|** Parameter **|`. The opening run is followed by a space, which makes it
  not an opening delimiter at all, and the header cell reads
  "** Parameter **".
- `developer/building_application/application_workloads/cronjob_create.mdx` —
  a stray closing `**` after "Failed jobs history limit". The sibling bullet
  one line above ends "Successful jobs history limit (default: 20)" with no
  such marker.

Both are also the source of the same defect in the Russian pages, which
reproduced the broken markup faithfully. Changing the English updates their
`sourceSHA`, so the translations are retranslated on the next run and the
defect goes with them.

Found by a new `no-unparsed-emphasis` lint rule rather than by reading:
measured across this repository it reports 2 English documents out of 922, and
both are these. Once doom ships that rule, these two would turn the English
lint red.
@youyongsong youyongsong changed the title fix(docs): four source defects the new translation checks brought to light fix(docs): six source defects the new translation checks brought to light Aug 26, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant