i18n support

[Ovilia]

How to generate documentation for different languages?

[tmcw]

That's a great question, and thus far I haven't seen a solid answer!

But to get conversation started, I'll propose a solution (though, only theoretical, there's no code on the ground for this):

The part of JSDoc that's in a human language is mainly the 'description' part, so in @param myVar The description, only The description should ever be translated: myVar should never be translated, because the software API won't change in a different language. Perhaps, for translations we could do something like:

Perhaps we could adopt the w3's advice for declaring language-specific content in a webpage, and use span tags, so a documentation block like

/**
  * @param myVar The description
  */

Would become

/**
  * @param myVar The description <span lang="es">La descripción</span>
  */

A likely gotcha here is going to be:

• We don't want to break existing documentation
• But we also don't want to be ethnocentric

My proposal would potentially be interpreted as ethnocentric, and could be improved by making the 'main' language configurable, so if the source language is Spanish, you could set the source language with an option.

Prior art here, I can only find this thread in JSDoc's repo and one fellow created a tool that uses an intermediary database to do translations. That'd also be an approach, and some folks may prioritize the need for using existing po-file based workflows. That makes me a bit nervous because documentation comments don't have consistent identities, so it'd be potentially a source of breakage when people refactor.

Open to other ideas or experiences - how can we do multilingual docs?

[Ovilia]

Thank your for your response. :)

We changed our plan to use markdown-to-html solution to generate our doc, considering the flexibility of controlling. But I do think i18n may be helpful for others. So I am going to close this issue, but will be glad to get updated.

Thank you again!

[nnmrts]

Can this issue be reopened please? I think this is still a valid question and a "missing" feature.

I can also just open a new issue but that would be kind of redundant.

[nnmrts]

Thanks for reopening it. Just gonna put out some thoughts here as well:

• Inline documentation translation would be bad design and imho ugly, not just ethnocentric
• The po-file based approach seems outdated and redundant in my mind; it may be suitable for UI contexts, but documentation often isn't just short distinct words
• I like the basic concept of the intermediary database approach of jsdoc-i18n, but it seems that it could behave kind of ambiguous sometimes, having a translation interface just for a short moment in time is weird; I have yet to try it out though

To me it looks like the jsdoc-i18n approach is the best option right now. I don't know though if you really need a full database, server and frontend for that. Something a bit more lightweight would be perfect in my opinion.