[LFX] Explore content-based detection for outdated localized documentation

# What would you like to be added?
Add a prototype tool for detecting potentially outdated localized documentation using content-based structural comparison, rather than relying primarily on timestamps or commit chronology.

This work is being explored as part of the #54075

The prototype would:

- compare the current English content state against the current localized content
- detect structural changes that likely require translation updates
- reduce noise from cosmetic upstream edits
- help localization maintainers prioritize review work

Rather than comparing text directly across languages, the prototype compares document structure (for example paragraphs, lists, code blocks, and shortcodes) within corresponding sections.

This prototype is intended as an experimental triage tool, not a strict enforcement mechanism.

The initial experiment may target:

- `language/ko`
- or smaller experiments such as `zh-tw`

The design goal is to keep the core system:

- deterministic
- lightweight
- easy to maintain
- inexpensive to run across large documentation trees

Semantic or AI-assisted analysis layers are considered optional extensions.

# Why is this needed?
Improving outdated-content detection can:

- reduce unnecessary review work for localization contributors
- help maintainers focus on translations that are most likely to be meaningfully out of sync with upstream documentation
- provide clearer signals for prioritizing translation updates

Existing tools often determine whether translations are outdated using simple signals such as:

- `Lastmod`
- file modification timestamps
- commit ordering

These signals are easy to compute but can produce misleading results.

## Failure mode 1 — False positives

English documentation often changes in ways that do not require translation updates, such as:

- formatting adjustments
- whitespace edits
- link updates
- shortcode refactors

These changes can trigger unnecessary outdated alerts and create additional review work for localization maintainers.

A previous attempt to improve outdated detection was PR #45844, which proposed a reporting tool based on modification timestamps and similarity signals.

## Failure mode 2 — False synchronization points (false negatives)

A more serious issue occurs when localized edits hide upstream changes.

Example scenario:

1. English documentation receives a meaningful update.
2. The localized page becomes outdated.
3. A contributor later makes a small cosmetic edit to the localized file.
4. That edit becomes the most recent localized commit.

If outdated detection relies on commit chronology, the earlier upstream change may be ignored.

This creates a false synchronization point, where the system incorrectly assumes the translation is up to date.

---

# Proposed detection pipeline

## Stage 1 — File discovery

The system identifies English and localized document pairs.

Git history may optionally assist candidate discovery (for example identifying recently modified English files), but is not used as the primary signal to avoid false negative.

---

## Stage 2 — Structural document comparison (pre-semantic filter)
The core stage analyzes the structural layout of the English and localized documents.

Rather than comparing text directly across languages, the tool parses each Markdown file into structural blocks such as:

- headings
- paragraphs
- lists
- code blocks
- shortcode/admonition blocks

This stage serves as an effective first-stage filter because direct text comparison across languages is often noisy, while translations typically preserve the document’s structural skeleton. As a result, meaningful upstream updates usually appear as structural changes that can be detected without language-specific analysis.

### Section alignment

Because localization frequently translates headings, sections must be aligned before structural comparison.

The system therefore aligns sections using signals such as:

- preserved heading anchors
- normalized heading text
- heading depth
- nearby structural context
- preserved technical tokens (for example `ClusterIP`, `NodePort`)
- structural fingerprints such as block counts

Once aligned, the tool compares the structural block counts within each section.

---

## Stage 3 — Intra-block comparison (content-aware heuristics)

If both documents share the same structural layout, additional heuristics can analyze changes within existing blocks.

Examples include:

- code block content differences (code is language-neutral)
- list item count differences
- shortcode parameter changes
- token-level differences in technical identifiers

These heuristics provide additional signals without requiring cross-language semantic understanding.

---

## Stage 4 — Optional semantic evaluation

If earlier stages detect potential drift, a smaller subset of documents could optionally be evaluated using semantic analysis tools or AI assistance.

This stage would run only on documents flagged by earlier filters, keeping the system efficient.

### Possible semantic analysis approaches

The semantic stage is not required for the initial prototype, but several approaches could be explored if additional filtering is needed.

#### Vector similarity / embedding comparison

Sections from English and localized documents could be converted into embeddings and compared using cosine similarity.

Large semantic differences between corresponding sections may indicate that the translation no longer reflects the upstream meaning.

#### Change summarization

Upstream English changes could be summarized automatically to help maintainers quickly understand what changed.

Examples:

- “New warning added about feature deprecation”
- “Additional configuration step introduced”

#### Heuristic semantic classification

Semantic tools could also classify certain categories of updates, such as:

- security-related updates
- version-specific changes
- API behavior changes
- newly added warnings or cautions

These signals could help maintainers prioritize translation work.

---

# Experiment setup

To evaluate the approach, the initial experiment will focus on a small set of English and Korean documentation pairs.

We may use a test script to create a test repository to simulate common localization scenarios, including:

- formatting-only upstream edits
- link updates
- shortcode refactors
- localized typo fixes that create false synchronization points
- normal upstream content additions

These scenarios help validate whether a detection approach correctly distinguishes:

- harmless upstream changes
- meaningful upstream content updates
- masked upstream updates

---

# Expected output

Example report:

```
File: content/ko/docs/tasks/foo.md
Status: candidate_outdated

Changed Sections:
- Prerequisites
- Command Usage

Signals:
- English paragraph added
- Code block updated
```

The output is intended to help maintainers identify and prioritize translation updates, rather than enforce strict synchronization.

Instead of producing a simple outdated flag, the system reports:

- affected sections
- structural change signals
- the types of changes detected

These signals help maintainers understand what changed upstream and how likely the change is to require translation work.

Examples of structural signals include:

- newly added sections
- additional paragraphs within an existing section
- new code blocks or configuration examples
- removed or missing structural elements
- shortcode or formatting changes

Different signals may imply different levels of urgency.

Example prioritization:

| Signal type | Example | Suggested priority |
|---|---|---|
| New section added | upstream adds `## New Requirements` | High |
| Missing paragraph | localized section has fewer paragraphs | Medium |
| Code example updated | code block content changed | Medium |
| Shortcode change | Hugo shortcode refactor | Low |

This allows maintainers to focus first on files that are most likely to require meaningful translation updates, rather than reviewing every upstream change.

Start by reviewing the related #54075 discussion, PR #45844, and the documentation under language/ko or zh-tw. Define the prototype and test scenarios for structural comparison, then verify that its report identifies affected sections and change signals without treating cosmetic edits as synchronization failures.

Written by the indexing model from the issue text.