Localized docs: translated or missing heading anchors can break deep links

[apullo777]

Problem:

While investigating localization consistency, I noticed that some localized pages change or omit explicit heading anchors from the English source.

For example, EN uses a stable explicit anchor:

## Desired versus current state {#desired-vs-current}

but a localized page may use a translated anchor:

## Stato desiderato versus corrente {#desiderato-vs-corrente}

or omit the explicit anchor entirely.

In most comparable cases I checked, when EN has an explicit heading anchor, the localized pages in the same locale appear to preserve that anchor. However, I found some exceptions across fr, it, es, de, and pt-br, where a few pages translate, change, or omit the explicit anchor while most other comparable pages in that locale preserve it.

This can make anchor behavior inconsistent within the affected locale and may break deep links that expect the English/source anchor to exist on localized pages.

From a manual audit of Latin-script localized pages, I found 24 confirmed anchor issues:

• 12 translated/changed anchors
• 11 missing anchors
• 1 anchor syntax typo/variant

Proposed Solution:

For each affected locale, the relevant l10n team can decide whether to align these pages with the majority pattern already used in that locale.

If preserving English/source anchors is preferred, the affected pages could be updated by:

• Replacing translated/changed anchors with the EN anchor.
• Adding missing explicit anchors where the localized heading clearly corresponds to the EN section.
• Fixing the syntax typo where the anchor was written as (#anchor) instead of {#anchor}.

Optionally, if docs maintainers think this should be documented, the localization guide could mention that explicit {#anchor} IDs may be preserved verbatim when that is the convention for the locale.

Page to Update:

French (fr)

Type	Page	Expected fix
translated anchor	content/fr/docs/concepts/architecture/cloud-controller.md	{#authorization-node-controller}
translated anchor	content/fr/docs/concepts/architecture/cloud-controller.md	{#authorization-route-controller}
translated anchor	content/fr/docs/concepts/architecture/cloud-controller.md	{#authorization-service-controller}
translated anchor	content/fr/docs/concepts/architecture/cloud-controller.md	{#authorization-miscellaneous}
translated anchor	content/fr/docs/concepts/architecture/cloud-controller.md	{#functions-of-the-ccm}
translated anchor	content/fr/docs/concepts/overview/_index.md	{#why-you-need-kubernetes-and-what-can-it-do}
translated anchor	content/fr/docs/concepts/overview/_index.md	{#going-back-in-time}
missing anchor	content/fr/docs/concepts/cluster-administration/logging.md	add {#basic-logging-in-kubernetes}
missing anchor	content/fr/docs/tasks/configure-pod-container/configure-service-account.md	add {#use-multiple-service-accounts}

Italian (it)

Type	Page	Expected fix
translated anchor	content/it/docs/concepts/architecture/controller.md	{#desired-vs-current}
translated anchor	content/it/docs/concepts/architecture/controller.md	{#running-controllers}
missing anchor	content/it/docs/concepts/cluster-administration/logging.md	add {#basic-logging-in-kubernetes}

German (de)

Type	Page	Expected fix
translated anchor	content/de/docs/concepts/architecture/cgroups.md	{#migrating-cgroupv2}

Spanish (es)

Type	Page	Expected fix
anchor syntax typo	content/es/docs/concepts/overview/working-with-objects/finalizers.md	change (#owners-labels-finalizers) to {#owners-labels-finalizers}
missing anchor	content/es/docs/tasks/debug/debug-cluster/audit.md	add {#batching} to the matching “Procesamiento por lotes” heading

Brazilian Portuguese (pt-br)

Type	Page	Expected fix
translated anchor	content/pt-br/docs/concepts/scheduling-eviction/kube-scheduler.md	{#scheduling}
translated anchor	content/pt-br/docs/concepts/scheduling-eviction/kube-scheduler.md	{#kube-scheduler-implementation}
missing anchor	content/pt-br/docs/concepts/cluster-administration/logging.md	add {#basic-logging-in-kubernetes}
missing anchor	content/pt-br/docs/concepts/extend-kubernetes/operator.md	add {#example}
missing anchor	content/pt-br/docs/concepts/extend-kubernetes/operator.md	add {#using-operators}
missing anchor	content/pt-br/docs/concepts/extend-kubernetes/operator.md	add {#writing-operator}
missing anchor	content/pt-br/docs/reference/access-authn-authz/authorization.md	add {#determine-whether-a-request-is-allowed-or-denied}
missing anchor	content/pt-br/docs/concepts/overview/_index.md	add {#going-back-in-time} to the matching “Voltando no tempo” heading
missing anchor	content/pt-br/docs/concepts/workloads/controllers/cron-jobs.md	add {#cron-job-limitations} to the matching “Limitações do CronJob” heading

These seem like small mechanical fixes that improve cross-language deep-link stability and make anchor behavior more consistent within each affected locale.

Affected locales: fr, it, es, de, pt-br

/sig docs
/area localization

[apullo777]

/assign

[lmktfy]

I don't really think this is a bug.

Each localization team can pick whether to use fragment identifiers that are the same as the English page, or not.

Whichever way they do it, localization teams are responsible for being consistent within their localization.

Do we need to force a particular way of working across all localizations? I don't think we do.

[apullo777]

Whichever way they do it, localization teams are responsible for being consistent within their localization.
Do we need to force a particular way of working across all localizations? I don't think we do.

Hi @lmktfy thanks for the clarification! I agree with your point.

I think I may not have explained my intention clearly. I’m not suggesting enforcing one approach across all localizations.

What I wanted to point out is that, in most comparable cases where the English page has an explicit heading anchor, the localized pages appear to preserve that anchor. But I noticed a few cases across several locales where the anchor is translated or omitted instead, even though most other pages in those same locales preserve it.

So I mainly wanted to flag that inconsistency and let the respective l10n teams decide whether they’d like to align it within their locale.

I opened the French PR as an example, thinking that it might be easier for me to identify and update those specific places directly. But I’m also happy to leave this to each l10n team to handle if that’s preferred.

[lmktfy]

It's great that you opened a PR covering just one localization. Some teams have a clea4 convention; others don't.

[apullo777]

I realize my issue description might have sounded a bit like I was suggesting a cross-localization rule. I updated it to make it clearer that this is more about consistency within each locale, and leave it to each l10n team to decide their preferred approach.

[seokho-son]

I think this issue is reporting broken links due to missing explicit anchors.

/triage accepted