[i18n] Support for external link in another language

[Chrissdroid]

Adding a component to specify what language the link is referring to

like so :

see docs for the <External-link lang="fr" href="https://developer.mozilla.org/fr/docs/Web/API/Request">Request</External-link> api in french

which is transformed in something like so :

see docs for the Request⁽ᴱᴺ⁾ api in french

[yanthomasdev]

Maybe we don't need a custom component for this. I just need to be sure if there is any downsides using <a> tag instead of Markdown link syntax, but with CSS pseudo-elements I can make exactly what you want with a few lines of css:

a::after {
	display: inline-block;
	content: attr(hreflang);
	font-size: 0.7rem;
	position: relative;
	bottom: 0.2rem;
}

What happens is that when an a tag has the hreflang attribute (this attribute specifies the linked document language), the content attribute will get the value (hreflang is case-insensitive, so as far as I know we have to write it in uppercase to be like that in the markup but that doesn't affect screen readers/SEO).

Final result:

[sarah11918]

I'm also not sure whether there is any problem created by using an <a> tag for a link on the site.

It's a bit of extra work for the translators! So, just making sure that the benefit of seeing the link of the language outweighs needing to write more for the link than just Markdown. :)

[delucis]

@Yan-Thomas

You can even get this with Markdown links to avoid complicating authoring:

html:not([lang="en"]) a[href^="/en/"]::after {
  content: " en";
}

Requires a CSS declaration for each language but we could probably auto-generate it once #365 is merged as that adds src/i18n/languages.ts with a list of all the languages.

Whether the content is upper or lowercase is not so important because we could style that with CSS too:

a::after {
  text-transform: uppercase;
  vertical-align: super;
  font-size: 0.75em;
  font-weight: bold;
  line-height: 1;
}

Alternatively, a remark plug-in could add hreflang to links based on a similar logic if you think that attribute has value beyond just styling. Might be better for SEO? (That approach could even inject the content itself instead of using CSS content, which might be desirable because of the accessibility of CSS content. An injected span could have a title “English version” for example, which we can’t do with CSS content.)

[yanthomasdev]

Thanks @delucis, clever solution! Also, I had totally forgotten about vertical-align and text-transform 🤣

I did some tests based on your approach using <span> and it really is better acessibility-wise (NVDA on Windows). I also totally forgot that CSS content isn't readable for screen reader users, I was really tired yesterday 😓

The hreflang attribute AFAIK is very specific (only used by Google SEO) and would just be a convenient way to express that the link is in a different language. If we can make this work without it, then be it!

[sarah11918]

@Yan-Thomas and everyone, do you think we can close the existing PR then, and continue to discuss here what solution we want for this?

In Discord, we also had the points:

By @delucis - We could just make the TEXT of the link include (en), and then no one has to write any differently!

By @kevinzunigacuellar (I think this is the correct Kevin Z!) - Keeping simple might be better, and is this really a problem to solve?

[yanthomasdev]

I agree with closing the PR and continue the discussion here, @sarah11918

Maybe this could be nice in this moment (where most pages aren't translated and updated yet), but as we translate new pages this loses importance IMO.

I also agree with being simple and just letting translators add "(EN)" to links. Maybe we can even document this in the i18n guide as a pattern for links in different languages?

[sarah11918]

I agree, @Yan-Thomas , and especially with all the sidebar links indicating which entire pages are in English, maybe it's less needed right now than we think?

[sarah11918]

Now that we have lots of pages translated, do we have more ideas/feelings about this, @Yan-Thomas ?

[delucis]

Something that came up recently was a desire to indicate that a link was to an English fallback version, so say you link to /de/fallback, the URL is “German”, but it hasn’t been translated yet so the content is in English. You can do this manually, but then when the page is translated your disclaimer is out of date and it’s hard to remember everywhere that needs updating.

I think we can avoid including disclaimers like this for now — so much is happening that a disclaimer seems likely to be out-of-date sooner rather than later. If we still feel like this kind of thing is helpful in a few weeks, I’d suggest exploring some kind of automated labelling of links similar to how we have the left sidebar set up.

[yanthomasdev]

Hi @sarah11918 , glad we are discussing this again!

As I was translating the docs to Brazilian Portuguese, I noticed some cases where we are linking to stuff that is English-only from other websites/blogs we do not control. Examples: Built with Astro and Partial Hydration pages.

The visual presentation if we added text manually isn't the best IMO, if we had something like[see this link{en}](http://test.com) I think would be the best approach, considering that some external links from other websites don't have "/en" as part of their URL.

This way we can safely add external links to the docs without worrying about users in other languages being confused about the fact that the link text/description is translated but the link content itself isn't.

[delucis]

Ohhh, I didn’t think about external links (which is literally in this issue’s title…)

Great point! Definite +1 on this. Also I think there are a few places where we link to MDN? A lot of those pages probably are available in other languages, e.g. https://developer.mozilla.org/pt-BR/docs/Web/API/Request, so maybe we also want to make sure to include that where possible.

So we have two use cases:

1. Internal content that hasn’t been translated yet (labelling can be automated to vanish when no longer needed)
2. External content that doesn’t exist in a non-English version (labelling has to be done manually inline)