kubernetes / kubernetes/website

[zh-cn] inconsistent heading levels in some localized pages

Open
#55,612 2 comments 1 reaction 1 assignee Claimed by @apullo777 View on GitHub
area/localization kind/bug language/zh needs-triage sig/docs
Dominant language
HTML
Stars
5.4k
Forks
15.7k
Avg merge
4d 18h
Merged PRs (30d)
204

Description

**This is a Bug Report**

**Problem:**

While exploring localization outdatedness detection, I noticed that some zh-cn pages do not preserve heading levels from the English source, which deviates from the zh-cn localization guide.

The expected convention is to preserve heading hierarchy:

- EN H2 → zh-cn H2
- EN H3 → zh-cn H3

However, there are two types of inconsistencies:

H2 → H3 (level downshift)

```

### 中文标题 {#english-title}
```

H3 → H2 (level upshift)

```

## 中文标题 {#english-title}
```

From a scan of 1861 zh-cn/en page pairs:

- 20 confirmed cases of H2 → H3
- 22 confirmed cases of H3 → H2

These inconsistencies appear to be rare (~2.3% of pages) but deviate from the standard pattern used in the majority of zh-cn docs.

User impact:

- Heading hierarchy becomes inconsistent with the English source
- Sections that are siblings in EN may appear as parent/child in zh-cn
- TOC structure differs between EN and zh-cn, which may affect navigation clarity
- A few cases also include anchor mismatches/typos

**Proposed Solution:**

For affected pages:

- Align zh-cn heading levels with the English source.
- Preserve explicit anchors `{#...}` where present.
- Fix obvious anchor typos or mismatches found during review.
- Before submitting a PR, run `./scripts/lsync.sh` on each touched zh-cn file.
- Avoid partial updates: if a touched file has additional upstream changes, include the full required sync or split it into a separate PR.
- Split the work into several smaller PRs grouped by docs area to make review easier.

Per the zh-cn localization guide, we should avoid partial updates to zh-cn files. If a PR touches a zh-cn file, that file should remain fully synchronized with the corresponding English source according to `./scripts/lsync.sh`.

If `lsync.sh` reports additional upstream differences, the PR touching that file should include the full required sync/translation for that file, or the file should be moved to a separate follow-up PR.

**Planned PR Batches:**

The exact batching may change slightly during implementation, depending on `./scripts/lsync.sh` results on the latest `upstream/main`.

### EN H2 → zh-cn H3 cases

#### Batch A1: docs/concepts

| Direction | Page |
|---|---|
| EN H2 → zh-cn H3 | `content/zh-cn/docs/concepts/architecture/nodes.md` |
| EN H2 → zh-cn H3 | `content/zh-cn/docs/concepts/cluster-administration/logging.md` |
| EN H2 → zh-cn H3 | `content/zh-cn/docs/concepts/scheduling-eviction/node-pressure-eviction.md` |
| EN H2 → zh-cn H3 | `content/zh-cn/docs/concepts/services-networking/dns-pod-service.md` |
| EN H2 → zh-cn H3 | `content/zh-cn/docs/concepts/storage/storage-classes.md` |
| EN H2 → zh-cn H3 | `content/zh-cn/docs/concepts/workloads/pods/_index.md` |

#### Batch A2: docs/reference

| Direction | Page |
|---|---|
| EN H2 → zh-cn H3 | `content/zh-cn/docs/reference/access-authn-authz/bootstrap-tokens.md` |
| EN H2 → zh-cn H3 | `content/zh-cn/docs/reference/debug-cluster/flow-control.md` |
| EN H2 → zh-cn H3 | `content/zh-cn/docs/reference/node/node-status.md` |
| EN H2 → zh-cn H3 | `content/zh-cn/docs/reference/using-api/deprecation-policy.md` |

#### Batch A3: docs/setup + docs/contribute

| Direction | Page |
|---|---|
| EN H2 → zh-cn H3 | `content/zh-cn/docs/contribute/localization.md` |
| EN H2 → zh-cn H3 | `content/zh-cn/docs/setup/best-practices/cluster-large.md` |
| EN H2 → zh-cn H3 | `content/zh-cn/docs/setup/production-environment/_index.md` |

#### Batch A4: docs/tasks

| Direction | Page |
|---|---|
| EN H2 → zh-cn H3 | `content/zh-cn/docs/tasks/access-application-cluster/access-cluster.md` |
| EN H2 → zh-cn H3 | `content/zh-cn/docs/tasks/access-application-cluster/connecting-frontend-backend.md` |
| EN H2 → zh-cn H3 | `content/zh-cn/docs/tasks/administer-cluster/kms-provider.md` |
| EN H2 → zh-cn H3 | `content/zh-cn/docs/tasks/configure-pod-container/configure-pod-configmap.md` |
| EN H2 → zh-cn H3 | `content/zh-cn/docs/tasks/debug/debug-application/debug-service.md` |
| EN H2 → zh-cn H3 | `content/zh-cn/docs/tasks/run-application/access-api-from-pod.md` |

#### Batch A5: topology-manager
| Direction | Page |
|---|---|
| EN H2 → zh-cn H3 | `content/zh-cn/docs/tasks/administer-cluster/topology-manager.md` |

Note: `content/zh-cn/docs/tasks/administer-cluster/topology-manager.md` require a small additional sync.

### EN H3 → zh-cn H2 cases

#### Batch B1: blog posts

| Direction | Page |
|---|---|
| EN H3 → zh-cn H2 | `content/zh-cn/blog/_posts/2022/forensic-container-checkpointing/index.md` |
| EN H3 → zh-cn H2 | `content/zh-cn/blog/_posts/2024/consistent-read-from-cache.md` |

#### Batch B2: docs/concepts + docs/setup + docs/tutorials heading-only files

| Direction | Page |
|---|---|
| EN H3 → zh-cn H2 | `content/zh-cn/docs/concepts/overview/components.md` |
| EN H3 → zh-cn H2 | `content/zh-cn/docs/concepts/scheduling-eviction/assign-pod-node.md` |
| EN H3 → zh-cn H2 | `content/zh-cn/docs/setup/production-environment/tools/kubeadm/control-plane-flags.md` |
| EN H3 → zh-cn H2 | `content/zh-cn/docs/tutorials/services/source-ip.md` |

#### Batch B3: docs/tasks

| Direction | Page |
|---|---|
| EN H3 → zh-cn H2 | `content/zh-cn/docs/tasks/administer-cluster/configure-upgrade-etcd.md` |
| EN H3 → zh-cn H2 | `content/zh-cn/docs/tasks/administer-cluster/encrypt-data.md` |
| EN H3 → zh-cn H2 | `content/zh-cn/docs/tasks/configmap-secret/managing-secret-using-kubectl.md` |
| EN H3 → zh-cn H2 | `content/zh-cn/docs/tasks/configure-pod-container/configure-service-account.md` |
| EN H3 → zh-cn H2 | `content/zh-cn/docs/tasks/configure-pod-container/extended-resource.md` |
| EN H3 → zh-cn H2 | `content/zh-cn/docs/tasks/debug/debug-application/debug-running-pod.md` |
| EN H3 → zh-cn H2 | `content/zh-cn/docs/tasks/debug/debug-cluster/windows.md` |
| EN H3 → zh-cn H2 | `content/zh-cn/docs/tasks/job/pod-failure-policy.md` |

#### Batch B4: docs/concepts files requiring additional sync

| Direction | Page | Note |
|---|---|---|
| EN H3 → zh-cn H2 | `content/zh-cn/docs/concepts/cluster-administration/node-shutdown.md` | Requires small upstream sync if `lsync.sh` still reports differences |
| EN H3 → zh-cn H2 | `content/zh-cn/docs/concepts/configuration/manage-resources-containers.md` | Requires small upstream sync if `lsync.sh` still reports differences |
| EN H3 → zh-cn H2 | `content/zh-cn/docs/concepts/storage/persistent-volumes.md` | Requires medium upstream sync if `lsync.sh` still reports differences |

#### Batch B5: large docs/concepts sync files

| Direction | Page | Note |
|---|---|---|
| EN H3 → zh-cn H2 | `content/zh-cn/docs/concepts/configuration/liveness-readiness-startup-probes.md` | Large upstream sync; likely should be isolated |
| EN H3 → zh-cn H2 | `content/zh-cn/docs/concepts/policy/resource-quotas.md` | Large upstream sync; likely should be isolated and may need translation review |

#### Batch B6: docs/reference

| Direction | Page | Note |
|---|---|---|
| EN H3 → zh-cn H2 | `content/zh-cn/docs/reference/access-authn-authz/admission-controllers.md` | |
| EN H3 → zh-cn H2 | `content/zh-cn/docs/reference/labels-annotations-taints/_index.md` | May require small upstream sync if `lsync.sh` still reports differences |
| EN H3 → zh-cn H2 | `content/zh-cn/docs/reference/using-api/server-side-apply.md` | |

/sig docs
/area localization
/language zh

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.