i18n/multi-language support?

[RobinQu]

Hi,

Targeted developers of my project may come from different countries.

Any solution for jsdoc to support writing jsdoc for multiple lauanges?

[bobhairgrove]

This is something I have been looking into just the past few days. Unfortunately, as to the strings which are generated by the JSDoc code itself, these are hard-coded in the application's default templates. They are scattered through publish.js (just look at the function "buildNav", for example) as well as several files in the tmpl folder.

I was able to create a German version by copying the entire contents of the default template to another folder and editing the strings I needed. Then I can call jsdoc with the -t argument and it uses that template. But this is more of a nasty hack, obviously not a good solution.

There is a plugin called jsdoc-i18n-plugin. It was meant as a tool for translating the comments (doclets) in the JS user code, not for strings used by JSDoc itself. It crashed the first time I used it because it tries to create a directory -- possibly a permissions thing (on Linux), but after I created the "locales/de_DE" folder it seemed to work. What it does is to create a simple JSON file which can be used for translations, but there is no instruction or documentation on how to get the translation back into jsdoc once it is finished.

It would take some effort on the developers' part to configure jsdoc for multiple languages, and after looking around on the internet, it seems there is no standard way of doing this for JavaScript. Some good ideas can be found on this site: http://wiki.commonjs.org/wiki/I18n_Proposal_A, but they would have to be implemented somehow.

[hegemonic]

Unfortunately, JSDoc's default template is not localizable--as @bobhairgrove says, you have to fork the template to modify the hard-coded strings. I'm working on a new template, called Baseline, that is fully localizable.

I'm not aware of any projects that have used JSDoc to provide docs in multiple languages, and I don't think there is a simple solution for doing so.

[bobhairgrove]

I just had a look at the Baseline template file "en.yaml" in the lang subfolder. It looks promising! I assume that there is some kind of tool for translators so that they do not have to edit the .yaml file directly? Can we use .po format, for example? Or the online Ruby translation service I found here?

What sort of engine will handle the plural forms? This is probably one of the trickiest parts of i18n because many languages have more than one case. In Russian, for example, plurals are different depending on whether there is 0; 1; 2 to 4; 5 or more up through 19, then the grammatical endings repeat ... 21,22-24, 25-30, etc.)

[hegemonic]

I assume that there is some kind of tool for translators so that they do not have to edit the .yaml file directly? ...What sort of engine will handle the plural forms?

No, there's no special tool for editing the .yaml file. But I quote from the README for the message-formatting library that Baseline uses:

The message syntax that this package uses is not proprietary, in fact it's a common standard message syntax that works across programming languages and one that professional translators are familiar with. This package uses the ICU Message syntax and works for all CLDR languages which have pluralization rules defined.

The message format should be flexible enough to handle languages with weird pluralization rules.

[AlmirKadric]

Hi guys, I know this is an old topic. But I came across it when I was looking for a i18n tool solution for JSDoc and honestly after much searching I didn't find anything that met my needs. In light of that I developed my own over the last week or so and published it to npm. Thought it sensible to add a note to this thread in case anyone else ends up in a similar situation looking for a similar tool.

Github: https://github.com/AlmirKadric-Published/jsdoc-i18n
NPM: https://www.npmjs.com/package/jsdoc-i18n