Alias german anchors in single file

[kleinerpirat]

What if we alias the auto-generated header anchors with the original ones?

Markdown offers reference style links, which are defined the following way:

[id]: url "title (optional)"

These can be used inline this: [This is a link to url][id]

This means we could alias the german anchors with the original paths, so different translators wouldn't have to worry about the header translations of other files. This would remove the requirement to translate anchors inline - we'd only have to replace the standard links with the bracketed reference-style across the manual once.

There's a limitation though: the references need to be defined in the file they're used in. That would be a showstopper, if mdBook didn't allow including portions of a file with templating syntax.

Say, we have a file called headers.md and alias all headers like this:

// ANCHOR: aliases
...
[studying.md#display-order]: editing.md#anzeigereihenfolge "Anzeigereihenfolge"
...
// ANCHOR_END: aliases

Then we could include these definitions on the last line (to avoid breaking the diff) of every chapter with

{{#include headers.md:aliases}}

and anchors like [Anzeigereihenfolge][studying.md#display-order] would work across the manual.

How would the workflow look like?

When a translator initially translates a heading, he'll have to alias the translated version in headers.md and update the alias on change. Advantage: The translator doesn't need to touch the paths of inline references at all.

[RumovZ]

I appreciate the problem you're trying to solve and it's a smart application of the existing tools, but I'm not convinced it's less work this way. We have a linkchecker, so my current approach would be not to care about broken links for now, and make replacements for the reported breakages globally when the translation is finished. On the other hand with a headers.md, you don't have to update any anchor links when transalting a file. But you have to update all of the file's anchors in headers.md. I believe there are more anchors than links to anchors, and a linked anchor often has more than one link pointing to it, so might this not end up being more work?

[kleinerpirat]

Ah, using a linkchecker and fixing links afterwards sounds solid too and is probably less effort than what I'm proposing here.

The reason why I tinkered with this was the realization that there will often be links from other files that would need to be updated individually for each header that gets translated. I thought it would ne neat to have everything in one place and not worry about any anchors that are scattered about in the manual.

Another motivation was consistency with the original. The chapters have the original english names, but the sections don't.

a linked anchor often has more than one link pointing to it

Wouldn't this be an argument for a headers.md? At least I don't see how it would be one against it.

---

I'm really not sure which way is better. Time will tell I guess. But at least we know it would be possible, should the need arise :)

[RumovZ]

Wouldn't this be an argument for a headers.md? At least I don't see how it would be one against it.

Sorry, that was a bit too shortened. I'll try again: From the existing anchor links, some point to the same anchor, so the number of linked anchors is even lower than the number of anchor links. This in turn would mean more redundant translations in headers.md. And for the current approach, multiple links to the same anchor aren't more work either, because IDEs like VSC allow for making replacements across the entire codebase. So we only have to run #adding-editing -> #hinzufügen-bearbeiten once, when the linkchecker tells us to.

In other words, the effort for maintaining a headers.md increases with the number of anchors, whereas the effort of the current approach only increases with the number of anchors that are linked somewhere.

I'm really not sure which way is better. Time will tell I guess. But at least we know it would be possible, should the need arise :)

Agreed. 🙂