Translations: injected text should be translatable

[humitos]

We are generating and injecting some HTML code on the page. How are we going to make that text translatable?

• https://guillaumepotier.github.io/gettext.js/
• https://www.i18next.com/
• http://messageformat.github.io/Jed/

[agjohnson]

Making strings translated isn't a big jump, there is tooling here that we're not yet using.

The problem here is a bit deeper though, and the larger issue will be in using the translations. We really should give the user a localized response from the API, based on the reader's browser language or documentation translation language, and we need this JS to come to the same conclusion about the language to use for translated strings.

[humitos]

We really should give the user a localized response from the API, based on the reader's browser language or documentation translation language

We are not returning strings to be read by the user from the API. These strings are in Javascript code now.

[agjohnson]

Well, there's nothing in the response yet, but I think we do have to expand this API response a bit too. Nothing too major, but for instance:

https://github.com/readthedocs/readthedocs-client/blob/main/public/_/readthedocs-config.json#L9-L10

That's just using Version.slug for now, but we should probably use Version.verbose_name for the link text and Version.slug for the URL. For pull request versions, this would include the translated provider terminology for pull request/merge request/etc. I hit this exact issue on the dashboard templates and had to pass this all back to the JS from the backend.

Also, I think it could make sense to use our existing v3 API serializers instead of a separate, truncated implementation of these for this particular API. This would also include more translated strings.

[humitos]

I'm not talking about the text or anything coming from the backend --we already know how to handle those. However, there is still going to be text in the client, like the flyout sections, the warning banners, the "Loading ..." message in hoverxref, and any other text we want to show from the client to the user. I'm thinking about those ones.

[agjohnson]

Yup, understood. I'm mentioning the API response in addition to this because it's related.

This library has some native translated strings only used in this library (ie "Loading"), but we will also end up with strings translated through the backend response as we fill out the API data structure more (ie "Pull request 1234"), and there will be some strings that could come from the backend if we wanted (ie "This documentation is for an outdated version latest").

How JS translations are recommended in the Django world is to gettext translate the JavaScript sources, but then the Django application serves a dedicated view/URL that responds with the localized strings (JavaScriptCatalog). This guide shows everything working together:

https://localizely.com/blog/django-i18n-tutorial/

I'm not using this pattern on the dashboard yet, but it's feeling like a better pattern the more I avoid it.

I'm not sure how applicable this particular pattern is to this library yet though. I'm not suggesting it for native strings to this library though.

[agjohnson]

It's not a target for this initial pass at this work, but the next step here would be outputting gettext catalogs for this library. We can decide how to use the catalogs later, but likely will need them either way.

[agjohnson]

I was going to bring this up this week. This repo could be a good fit if we want to try using Crowdin to push translation management to GitHub. Translation volume is low and it's new.

On the tooling front, I just want to ensure that the translation tools/packages we use here are the same we use on the dashboard, so we don't have differing tech. The dashboard is not doing any translation in JS yet and pushing all of this to Django and templates instead, which is not great.

But the JS tech is largely not great here either. Most solutions just request or import localized strings from a separate JS or JSON file.

We can visit the API localization later. It's less of an issue, though there are strings in there we'll have to do something with:

• https://github.com/readthedocs/addons/blob/2dfab0c84f6cd0ec6e055466fd6ae5bd8d24d1a1/public/_/readthedocs-addons.json#L132
• https://github.com/readthedocs/addons/blob/2dfab0c84f6cd0ec6e055466fd6ae5bd8d24d1a1/public/_/readthedocs-addons.json#L149