Skip to content

AlmirKadric-Published/jsdoc-i18n

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

12 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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.