google/comprehensive-rust

Link to correct line when editing a translation

Open

#1,075 opened on Aug 13, 2023

View on GitHub
 (6 comments) (0 reactions) (0 assignees)Rust (32,954 stars) (2,009 forks)batch import
enhancementgood first issuehelp wanted

Description

On a whim, I tried adding a #Lnnn fragment to a URL which opens the GitHub code editor... and it works! Check out line 3456 of the Korean translation.

With this, we are able to create useful links on the published pages for the translations. Currently, we simply link to the xx.po file, but we should instead link to the first message of each page. We could do so in a few different ways:

  • We could post-process the HTML. Something like loading each page, find the first paragraph, look it up in the xx.po file, get the line number, inject the line number into the link on the page.
  • We could use the GitHub API to download the file on demand when clicking the edit link. We would then search like above and send people to the right spot in the editor. The PO files are 500-800 KB in size, so that might be a little heavy-handed.

We could go with a hybrid version: generate and publish a small xx.json file with the correct line number for every path. Then download this file when clicking the link. That ought to be fairly simple since it's easy to load JSON files from JavaScript, and it will be pretty simple to produce this file when we publish the course.

Implementing this would drastically improve the editing experience for our translators.

Contributor guide

Tech stack
rusthtmljavascript
Domain
documentationlocalization
Issue type
feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
half day
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
Basic RustPO file formatHTML/JavaScript
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
30
Research direction
Review the issue comments and existing translation infrastructure in the repository. The suggested hybrid approach is to generate a small JSON file mapping page paths to line numbers in the PO file during the build process. Implement a script (likely in Rust) that parses the PO files and outputs the JSON. Then modify the HTML template that renders the edit links to load this JSON and redirect users to the correct line (e.g., https://github.com/google/comprehensive rust/edit/main/po/xx.po#Lnnn). Key files to examine: the build script (likely in src/ or a Makefile), the HTML template for translation pages, and an example PO file in po/.