nuxt
internationalisation for nuxt.com
we'd love to have the nuxt.com docs available in translations for users across the world
although this has been a plan for some time, and was indeed the case in nuxt v2, we're still not there with v3 docs
Related issues: https://github.com/nuxt/nuxt/issues/19926, https://github.com/nuxt/nuxt/issues/21926, https://github.com/nuxt/nuxt/discussions/16054, https://github.com/nuxt/nuxt.com/issues/1448 and https://github.com/nuxt/translations/discussions/4 (private repo - relevant content copied into this issue).
Key requirements
- needs to be performant and not regress performance of the documentation
- translations need to remain always in sync, falling back to english text if required
- needs to allow community contribution
Translation and sync automation
Documentation sources currently come from https://github.com/nuxt/nuxt.com, https://github.com/nuxt/nuxt and https://github.com/nuxt/examples. upstream changes need to be localisable, and trigger call for updates for translators, without blocking the documentation.
It would be nice to consider exploring LLM triggers for translation (see for example the way https://github.com/formkit uses ai in the process of building their documentation website) - at least for 'fallback' content.
👉 See https://github.com/nuxt/nuxt/discussions/29949 for a proposal
Building a team
We've had many offers of help for translating the docs, and we'll need to build a team - but first we need to add the infrastructure to make updating translations possible.
So initially I would love for someone or a small group to take on the task of building up the automation + integration into the nuxt/nuxt.com repository, before we move ahead to create a bigger team of translators.
I am thinking that it might be beneficial to use some type of DB or use @nuxtjs/i18n with server side translations, so that it can be easily changed. I see that some of the routes I pre-rendered (from looking at nuxt.com nuxt.config.ts file), so of course that would need to be taken into account.
I started maintaining the Nuxt Simplified Chinese documentation six months ago. The current method I use is to translate simultaneously across the three repositories: nuxt/nuxt, nuxt/nuxt.com, and nuxt/examples, merging upstream updates using git diff to keep the documentation translation up to date.
For more details, you can check the Nuxt Chinese documentation repository https://github.com/zhcndoc/nuxt
If the Nuxt official has a better translation process, I am willing to join in contributing to the translation and synchronize all existing translation results to the official Nuxt translation.
Nuxt Chinese documentation: https://nuxt.zhcndoc.com
It seems like the main nuxt.com website could be translated with the nuxt/i18n library but the main "problem" would be translating the nuxt docs and also the nuxt examples which are both using nuxt/content.
It seems like the main nuxt.com website could be translated with the nuxt/i18n library but the main "problem" would be translating the nuxt docs and also the nuxt examples which are both using nuxt/content.
nuxt/i18n can use different routes to point to different files, such as /docs/getting-started/installation and /zh-cn/docs/getting-started/installation. I think the challenge lies in how to keep both in sync, and I'm not sure if https://github.com/lunariajs/lunaria can handle this task.
Chiming in, I'd be happy to help with anything necessary—either translation or building the infrastructure around it. Feel free to ping me when needed.
Hi @danielroe, Firstly, this is a great initiative thank you for it! I’d be happy to help translate Nuxt into Azerbaijani. I’m also the maintainer of the Azerbaijani channel in the Nuxt Discord.
Such amazing news - I'd be more than happy to help with the Czech translation! 🤙
I think a translation SaaS like Crowdin might be a good addon for the infrastructure. Integrates with vue-i18n, supports LLM translation and offers a smoother collaboration experience than PRs. Facebook's Docusaurus has been using it for quite a while.
Romanian version of the nuxt.com only main pages at the moment https://github.com/Makkalay/nuxt.com
Let's start creating a core team around this, and as Daniel said, after the infrastructure is ready it will be easy to get people to translate.
I just want more people to leave React and start enjoying the Vue
How does https://github.com/nuxt/nuxt/pull/31353 effect this? I think i18n docs should not be published as @nuxt/docs? But maybe we want to publish @nuxt/docs-i18n to possibly have nuxt devtools offline docs. 🤔
I also think that it should be as easy as possible for developers contributing to nuxt to add English docs and, if possible, docs in their own language (without blocking). So, if possible, there should not be x more steps required.
translations need to remain always in sync, falling back to english text if required
Fallbacks will only work if translations are missing (should be pretty rare), not if they are out of sync/not complete.
If we're planning on adding translations to the docs we really need to fallback to automated translations if new content is added/updated, perhaps showing a badge/icon/button to communicate when a section is machine translated. Ideally users could click on this to navigate them to some method (PR/form/inline diff editor) of suggesting an updated translation.
Maintaining (and writing) documentation in general is already difficult and time consuming, community driven translations will always lag behind the original source but are likely more accurate than machine translations. This is also why nuxt-i18n does not have translated documentation.
perhaps showing a badge/icon/button to communicate when a section is machine translated
But what about partial updates like changing or adding a paragraph? We should not do a paragraph-wise badge...
Ideally users could click on this to navigate them to some method (PR/form/inline diff editor) of suggesting an updated translation.
For this we need a mdn component to wrap all AI only translations.
The question is, what the "data flow" should look like.
Example:
english docs:
## Hydration Strategies
Nuxt provides a range of built-in hydration strategies. Only one strategy can be used per lazy component.
> [!WARNING]
> Currently Nuxt's built-in lazy hydration only works in single-file components (SFCs), and requires you to define the prop in the template (rather than spreading an object of props via v-bind).
german docs:
## Hydration Strategien
Nuxt bietet eine Reihe von Hydration Strategien. Nur eine kann kann pro Lazy-Komponente verwendet werden.
> [!WARNING]
> Derzeit funktioniert die in Nuxt eingebaute „Lazy Hydration“ nur in Single-File-Komponenten (SFCs) und erfordert, dass Sie die Props im template definieren (anstatt ein Objekt von Props über `v-bind` zu spreaden).
(thats actually a hard one to translate 😅)
If we now add: "It also does not work with direct imports from #components."
> [!WARNING]
> Currently Nuxt's built-in lazy hydration only works in single-file components (SFCs), and requires you to define the prop in the template (rather than spreading an object of props via `v-bind`). It also does not work with direct imports from `#components`.
We should synchronize this with the German translation. But
- What if someone adds a community contribution like a warning to the German docs. Should this also be synced back to the English translation?
- If so, how do we differentiate the localization-only changes and the "contribution" changes so that the sync process does not end up with the ai trying to loop itself.
- Can we get the AI to the point where it can and does add partial updates to all i18n docs?
What if someone adds a community contribution like a warning to the German docs. Should this also be synced back to the English translation? If so, how do we differentiate the localization-only changes and the "contribution" changes so that the sync process does not end up with the ai trying to loop itself.
I think it would be best to have one language be the single source of truth (likely english, as it is currently). Translations should strive to stay in sync with that source. Any additions to the documentation must be added to the 'source language' too, otherwise it becomes difficult to know which language is out of sync with the others.
This does add a barrier for people who would like to contribute don't feel comfortable writing in english, but without a workflow or rule like this, we would end up making our current documentation maintenance process more complicated.
I agree with treating English sentences as truth, but I think that synchronization of each translation is still a challenge.
The results of machine translation are usually good, but front-end terms and technical terms change rapidly, and machines often cannot choose the right phrases, which may confuse users.
I think it would be better to create machine translations only to reflect differences in the initial translation file (DB) generation and PR, and then have developers and translators review and reflect them upstream. What do you think?
Weblate's continuous localization seems to have a similar mindset, so please let me know your opinion. Do you think it will create other issues such as performance?
As the person behind the Portuguese translation of the v2.nuxt.com, I will be more than happy to help with the translation of v3 documentation to the same language.
I've used https://crowdin.com/ in the past for Laravel and Vue.js (v2) docs and it was great. It has a git like system which is perfect for this kind of project where the original source may be rewritten here and there. Users can also make contributions. They do also have licenses for Open Source projects. I'd love to help with this.
@danielroe I'd love to contribute to the translation efforts for Nuxt 3 documentation. I’m comfortable working with Vue/Nuxt and would be happy to help with:
- Translating the documentation into French
- Reviewing translations
Let me know how I can get started or where help is most needed.
@danielroe @ikxin If Chinese translation is needed, please also let me participate❤
@danielroe @ikxin If Chinese translation is needed, please also let me participate❤
At https://github.com/zhcndoc you can participate in most of the open source projects to contribute to the translation of the Chinese documentation