kubernetes / kubernetes/website

[LFX] Explore localization team status visibility reporting

Open
#55,213 6 comments 1 reaction 0 assignees View on GitHub
area/localization kind/feature lifecycle/stale needs-triage
Dominant language
HTML
Stars
5.4k
Forks
15.7k
Avg merge
4d 18h
Merged PRs (30d)
204

Description

# What would you like to be added?
I would like to explore a lightweight reporting helper for localization team status visibility.

The goal is to provide a simple way to see, at a glance, which localized files are most likely to need review based on better outdated-content signals, so localization maintainers can prioritize update work more effectively.

Rather than centering this work on Git recency alone, I want to explore a visibility/reporting layer that can eventually consume stronger signals from the content-based outdated detection work in #54896.

Possible initial prototype scope:
- accept a target localization language (for example ko)
- compare files that exist in both content/en/ and content/ko/
- summarize files that are most likely to deserve review based on available outdated-content signals
- output a ranked or grouped summary to help maintainers identify which files may deserve attention first
- keep the implementation lightweight and easy to maintain

This issue is part of the broader LFX localization workflow effort: https://github.com/kubernetes/website/issues/54075

# Why is this needed?
Today, localization contributors can inspect specific files or directories with existing tools such as `scripts/lsync.sh`, which is useful when working on a known target file.

However, there is still a separate workflow need: team-level visibility.

Examples of visibility questions include:
- Which files in our localization set are most likely to need review?
- Which areas should we review first in the next update cycle?
- How can maintainers quickly get a rough status snapshot for planning or reporting?

A lightweight visibility-oriented helper could support these workflows, especially if it is built on top of better outdated-content signals rather than relying only on timestamps or commit chronology.

This issue also builds on earlier exploration of localization reporting in #45844, but the goal here is not to continue with a Git-recency-based direction as the main approach. Instead, the intention is to explore a smaller visibility helper that can eventually align with the stronger content-based outdated detection work being explored in #54896.

In particular, this direction is intended to:

- keep the scope smaller and easier to review
- avoid claiming semantic or content-level freshness detection beyond what the underlying signals can support
- complement existing workflows such as `scripts/lsync.sh`, rather than replace them
- allow the reporting/visibility layer to evolve separately from the detector implementation details

This work is also separate from content-based outdated detection efforts. More advanced detection approaches can continue in their own workstream, while this issue focuses on a smaller visibility/reporting layer.

# Scope
Initial exploration scope:
- single-language reporting per run
- visibility/reporting based on available outdated-content signals
- ranked or grouped text output suitable for local maintainer use
- minimal implementation complexity
- easy to test and review

# Non-goals
This issue is not intended to:
- define the full outdated-content detection algorithm itself
- replace existing scripts
- introduce AI-, embedding-, or semantic-based comparison directly in this reporting layer
- enforce synchronization rules
- define a universal workflow for all localization teams

/area localization


Contributor guide

Open the contributing guide

Research direction

Start by reading scripts/lsync.sh and inspecting the corresponding files under content/en/ and content/ko/. Review the outdated-content signal work in #54896 and the earlier reporting exploration in #45844 before defining the prototype boundary. Done should be a tested, lightweight single-language report with ranked or grouped text output, without implementing the detector itself.

Written by the indexing model from the issue text.

Assessment

Domain
documentation, localization, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.