jsdoc-i18n

jsdoc-i18n is an internationalization workflow developed around the jsdoc documentation tool.

What this means exactly is:

you can export jsdoc data into an intermediate database
you can use the built in tool to create multiple translations of each jsdoc item
you can render these language variations into separate language folders

Also we really tried to make jsdoc-i18n an extension of the existing jsdoc tool, giving it a relatively small footprint. This means that the jsdoc configuration system, all existing jsdoc arguments, as well as existing jsdoc templates (with very minor patching) are supported.

Installation

To install jsdoc-i18n globally

npm install -g jsdoc-i18n

To add jsdoc-i18n as a dependency to you project

npm install --save jsdoc-i18n

Configuration

On top of the existing jsdoc configuration options, the following options are accepted under the i18n rootpath:

defaultLang: The default language existing documentation is written in (Default: en)
possibleLang: List of languages we can translate to (Default: ['zh', 'es', 'ja'])
dbPlugin: The jsdoc-i18n database plugin to be used when saving or retrieving jsdoc data. This can be either a filename or a string reference to one of the jsdoc-i18n internal database plugins (Default: file)
dbFilePath: Path to database json files for jsdoc-i18n internal database file plugin (Default: ./i18n)
serverPort: Port on which jsdoc-i18n translation web application tool should listen (Default: 8080)
serverCheckPaths: Paths which jsdoc-i18n translation web application tool tool check when a request is made (Default: ['.', 'index.html', 'index.htm'])

NOTE:
Currently these options cannot be set via command line. Therefore the configuration file argument is required for jsdoc-i18n to function properly.

Usage

To import jsdoc data to jsdoc-i18n database:
(Supports jsdoc arguments)

jsdoc-i18n-import -c path/to/your/conf.json path/to/files/to/be/parsed

To start jsdoc-i18n translation web application tool:
(http://localhost:8080)

jsdoc-i18n-server -c path/to/your/conf.json

To render data from jsdoc-i18n database with given language
(Supports jsdoc arguments)

jsdoc-i18n-render -c path/to/your/conf.json -l <language>

Caveats

Due to an issues in jsdoc ES6 class definitions cannot be inlined with export statements.
For example you cannot define an ES6 class like such:
```
  export default class SomeClass {
  }
```
Instead you will have to break the definition over 2 lines:
```
  class SomeClass {
  }

  export default SomeClass;
```

Due to the way jdodc-i18n works, you cannot document a class and it's constructor separately.
For example you cannot document an ES6 class like such:

  /**
   * @extends EventEmitter
   */
  class SomeClass extends EventEmitter {
    /**
     * @param {*} a - what a is for
     * @param {*} b - what b is for
     */
    constructor(a, b) {
    }
  }

Instead you should put the constructor documentation inside the class documentation:

  /**
   * @extends EventEmitter
   * @param {*} a - what a is for
   * @param {*} b - what b is for
   */
  class SomeClass extends EventEmitter {
    constructor(a, b) {
    }
  }

License

jsdoc-i18n is free software, licensed under the MIT License.
See the LICENSE.md file in this repository for more details.