smartLink() should fall back to English in some way

We have a lot of xrefs and sidebars (soon!) that use smartLink() and these can recover to fall back to English if the translated content doesn’t exist.

We can discuss implementation choices here. For example:

1. <a class="page-not-created" title="Not yet created ...">SomeApiMethod</a> <a href="/en-US/docs/SomeApiMethod">English</a>
2. <a title="Not available in Japanese. Falling back to English" href="/en-US/docs/SomeApiMethod">SomeApiMethod</a>
3. <small>In English</small> <a href="/en-US/docs/SomeApiMethod">SomeApiMethod</a>
4. (Chris’s suggestion) <a title="Page only currently available in English" href="/en-US/docs/SomeApiMethod">SomeApiMethod (en-US)</a>

Any other ideas?

[chrisdavidmills]

I feel a bit uneasy about solution 2. A little while back we got rid of the title tooltip stuff from all the *xref macros because of concern over accessibility bad practice. I believe the concern is that not all AT reads out the title contents consistently, , at least not by default, so you are supposed to not include any vital information in there, just extra “nice to have” information that isn’t vital for usage.

I can also see the problem of solution 1. Having an extra link to the English version after each non-existent page link could be really ugly, and detract from the user experience.

I think the knowledge that you are about to go to an English page is essential knowledge for site users, so it should be in the link text.

The knowledge that the page doesn’t exist yet, which is why they are being sent to the English page , isn’t essential knowledge to use the site, but it is useful knowledge, especially if you are a (would be) contributor. I’d therefore suggest that we use a variant of solution 2 along these lines:

<a title="Page only currently available in English" href="/en-US/docs/SomeApiMethod">
  SomeApiMethod (en-US)
</a>

So you have the essential information available in the link text (this is the English version you are going to), and the tooltip then gives more of a clue as to what is going on. I’d be happy to also combine this with a slightly different styling, plus a note on the Localization contribution page to explain what is gong on here in more detail.

[escattone]

Thanks for leading this discussion @peterbe! Let’s move ahead with @chrisdavidmills’ solution.