You can check out the platform Crowdin, maybe that's an option too.

We have already used in the past with @atinux and it wasn't a good solution 😅

This is a nice idea @Geminii to omit tag when translated. I mainly wanted to keep it so we can detect translation comments and distinguish them from other comments.

@Intevel Indeed we were using several platforms in past. The main issue is when depending on a cloud-based solution compared to GitHub, we are bound to platform possibilities while with a markdown-only approach we never have this risk yet will be able to integrate with cloud based solutions (think of git merge conflict annotations and how IDEs support them)

Maybe @kazupon has experience on this already, so please let me know if you got ideas/suggestions!

If we were to build a tool (does not have to necessarily be related to Nuxt itself) that is more geared towards managing markdown based documentation, each "translatable" single section could have 3 base states:

• not translated
• translated: for this, there could be sub states to translated to language X, language Y, etc...)
• outdated: it was translated before but thr original section has changed.

This could help keeping an overview of the documentation and its current state. An outdated section could then be flagged for any maintainers to try to either update the translation / get help to do it.

The issue with this is that keeping track of all these states in the MD file itself could be tricky (too much visual pollution and makes it difficult to read).

Your comment regarding an external database file @pi0, made me think of this. Was this something you already had in mind?

Maybe a way to match if a translated section is up to date or not is to generate a hash based on its content (assuming the base is always English).

The moment said content changes, all translations that point to it but have different "original content hashes". But that also means the each section needs to connect to its translations via some sort of key (order or section within original MD file might be enough)

Using hash-only, we cannot do fuzzy checks anymore (for the threshold of acceptable change)

We can have status + content ref like <-- [translated] e123:en/intro.md:10:20 --> instead of actually inlining contents. This can also be a configurable behavior.

What I'm afraid of about implicit refs, is that this would make the process more likely to human errors because we are still depending on manual and optional review. A maintainer can simply mark it as [translated] without bothering to check updates while with inlining contents, they can clearly see it above and if translation is not good enough, next person can use it as a reference without bothering to check another file.

I guess a relevant question is also how granular would you would like each translatable bit to be, i.e. each paragraph is a separate bit, file per file basis, everything under a sub-header is a bit, etc.

And should all these bits be checked separately.

Ignore that. You had already answered that initially 😅

What do you think about more semantic annotation to make it more readable for new users?

I agree with semantic annotation. With its introduction, new users will be able to read markdown content. In addition to that, it also allows a synchronization mechanism based on annotations with the script.

However, we need to define the syntax of semantic annotation so that the readability of the content is not reduced. One of the idea would be to use comment annotation like jsdoc.

embed content annotation syntax

short-content:

<!--
  en: '# Header 1'
  status: translateme
-->

long-content:

<!--
  en: `
    ::alert{type=warning}
    Hello
    ::
  `
  status: translateme
-->

reference content annotation syntax

<!--
  ref: en/intro.md
  line: 10
  column: 20
  status: translated
-->
# ヘッダー１

So, For we implement semantic annotation, we need to provide syntax highlight support for an IDE such as VSCode.
We already have a VSCode extension for docus, we just need to extend it! :)

would you prefer this to happen run-time? e.g. i'm a dev and i run localhost:4000/nuxt-docs which gives me english website by default and switching to localhost:4000/fr/nuxt-docs calls this translation on-the-go and servers everything.

With either multi source support from docus or temporary an internal script, we can render docs in dev as production. localhost:4000/en and localhost:4000/fr both will be available while working on docs.

would you rather have a "generate translated docs" script that would go through all the docs, sieve through all the existing translations, and generate everything that I can. said script could be called on GitHub actions locally for contributors to test their translations.

Exactly. The script is supposed to be triggered by Github actions periodically or ideally with a commit hook to immediately check differences, apply status changes and notify language maintainers. With such automation, we would never be worried about outdated translations. (Ambitiously we can potentially use google cloud translation API to create a trained model based on initial translations that can automatically apply domain-specific translations)

BTW we can also give that "manual button" to maintainers running script locally if the action goes wrong or needs a manual sync for any reason.

I like with the manual button thing. I think it would make it easier for contributors to test locally what they are doing, in a prod like situation

would you rather have a "generate translated docs" script that would go through all the docs, sieve through all the existing translations and generate everything that i can. said script could be called on github actions on locally for contributors to test their translations.

I think really so too. Recently, translation services are getting more and more accurate.
Especially for our software documents, It's not wierd to read the translated docs

I would add to this idea, so if you have outdated translated content, we should also translate it with a translation service and add it as an annotation along with the machine translated status.

@kazupon, I had not thought of that! that's a really good idea!
From the translation contributions that I've done, there were moments that I couldn't think how to explain certain phrases and google translator helped me a lot, i'd then take that translation and improve it but it did "unlock" me at that moment.