Internationalization in the documentation and its maintenance #14280
Replies: 1 comment 1 reply
|
First, thanks for your help with translations, much appreciated! 🙌🏽 Languages to maintain
I don't know about this. Not everyone is comfortable with English and having some pages translated in their language could help them. Especially beginners. That's why, in the translation guide, we list the pages to be translated first. This can help people new with Astro. Once they are sufficiently comfortable with Astro's concepts, they may find it less difficult to consult the English version when they encounter untranslated pages.
I agree: outdated translations are not helpful both for users and translators (it can be harder to update something really outdated rather than starting from scratch). We've done some clean up in the past because of that, and we might need to do it again. And even though the documentation is not entirely translated, we have active maintainers for Japanese. Deutsh and Traditional Chinese are also maintained, even if they focus solely on the pages to translate first. So, I don't think we should remove all languages except those you're listing. But, that's also why we always hesitate when it comes to adding new languages. Localized linksYes, this is always a delicate aspect when maintaining translations...
If you know that a link is causing a problem, you can also prioritize the translations to keep PRs small enough:
But this is not an approach we advertise because this implies translators needs to keep track of those changes and be active. It's easy to forget if A is done in March and B in April or later... If you know you can work on both files in a short period of time, then you can find workarounds that work for yourself as long as you communicate them to the reviewers in the PR.
If you mean the heading IDs, we already discussed that in #11181
This is not exactly true I think: when a translated page adds a link to a page not yet translated, it used the English id so we need to check if the English page contains it. That's said, maybe there are improvements to make to improve performance here. Lunaria's translation tracking
Yes, that's why some keywords in the PR title can be used to prevent the Lunaria status from being updated. So, except oversights maybe, I don't think this is an issue? Do you have a specific example in mind? Also, it's worth noting that a typo in English can affect other languages, even if that is not the case in your language. So, we might deliberately omit the ignore keywords. We can't check every translations to only update the status of affected languages: this is time consuming, and we might not speak that language, so we're not the best to judge if an update is required or not.
Lunaria already supports directives for fine-grained control over status update, if needed. But perhaps you had a specific case in mind that isn't covered by Lunaria's current features? Formatting consistencyYes, that would be nice, especially for code snippets (related to #10073). But: Prettier doesn't always play nice with MDX and can cause more issues. That's why it is disabled in this repo.
Not sure I understand what you mean by this. |
|
Hi again Armand 😊! Thanks again for taking the time to respond to this discussion and I hope you are having a great day! I'm going to go through it point by point and see if I've understood everything correctly. Languages to maintainI completely agree with what you said. At this point, it’s easy to see which languages could be removed since there are no contributions for them. To solve this, one option could be to hire one person per language to keep the documentation up to date. Considering the funds raised on Open Collective, I don’t think that would be such a bad idea. I know the beauty of open source is that developers contribute to these projects on their own without expecting anything in return, but if there are no active contributions, this could be an option. I'm certainly glad to be contributing to this amazing community. Localized links
I agree with you on this as well; at the end of the day, UX is one of the most important things. What I don't quite understand is why it's more work not to have to translate the links. Ultimately, you end up using the same links for all languages, and if you translate them, you have to keep checking all the time to make sure they're correct (even without translating them, you still have to check them, but at least they're already predefined). Lunaria's translation trackingFirst of all, I want to apologize because I should have done a little more research. I had no idea that Lunaria had that configuration, even though I did look through the docs a bit before creating this thread 😅. After looking at everything, it has everything we need, and I'll definitely keep it in mind for my next pull requests. Formatting consistencyAt this point, maybe a good option is to wait until biomejs adds support for Markdown/MDX. Also we can try to create a Prettier plugin for the code blocks (I'm not sure if that's possible). I'm going to do some searching to see if I can find anything related to MDX formatting.
By this I mean that, in my opinion, there are sections that aren't very clear, or pages that aren't very intuitive for the user. As an example, I'll mention the Deno docs. They have several sections, just like Astro, and they also include icons indicating the type of each item in sections like references, errors, and objects. Example from the Deno API reference. Just to add one more thing, it might also be a good idea to apply a little more styling to the components and the Markdown in the documentation. Use Astro’s primary or signature colors, apply a font to the text (we’re currently using the system default font), and implement a true dark theme. This isn’t necessary, but I wanted to mention it in this section. |
Uh oh!
There was an error while loading. Please reload this page.
Hi everyone, I'm a contributor to the Spanish-language docs with some experience working alongside @Waxer59 and @dreyfus92. I'd like to be able to discuss certain issues and get positive feedback from the conversation.
Languages to maintain
Currently, the docs consist of a large number of pages and, as a result, a huge amount of content. The problem here is that many of the available languages have few contributors or aren’t maintained consistently. It doesn’t make much sense to visit a translated page and find that all the surrounding content isn’t translated.
The request is to remove those languages that are unnecessary due to a lack of maintenance. In other words, the documentation would remain available in French, Korean, Chinese (zh-cn), and Spanish.
Localized links
One of the tasks that takes up the most time for documentation maintainers is managing links: checking their sources, translating them, and keeping them up to date. Often, when updating a single page, we end up including other files in the same pull request simply because of these links.
This practice is beneficial for SEO, but is it truly necessary? Other documentation projects, such as Vite's, do not localize links even though they support multiple languages, just like Astro.
As mentioned above, a significant amount of time is spent checking that links are correct. Since localized references are only used within their respective language, the GitHub workflow could be improved to check only the files belonging to that specific language.
Lunaria's translation tracking
Another point worth discussing is Lunaria, the tool used to track translation status across languages. Currently, applying certain changes to a page causes the corresponding pages in all other languages to be marked as outdated, even when the change doesn't actually affect their content or meaning. It would be worth exploring ways to improve Lunaria so that certain types of changes can be applied without automatically flagging every other language version as out of date.
Formatting consistency
Another improvement worth considering is introducing a Markdown/MDX formatter to keep pages consistent across the documentation. Since Astro's docs use MDX, a formatter that supports both Markdown and MDX syntax would help prevent trivial mistakes and ensure a uniform structure across all files. The repository supports EditorConfig, but it's not quite enough
Thanks Astro
As a contributor to the spanish docs, I'm committed to actively maintaining them going forward, including following all guidelines as closely as possible, even if that means removing the language entirely, should that be the best course of action.
It would also be worth reviewing the current content and discussing a better way to organize it, so it can be managed and maintained more effectively going forward. A good idea could be creating a new branch in the repository to implement these changes.
All reactions