[api-extractor] Is there some way to support multiple language

[Jeffy2012]

Is this a feature or a bug?

• [X] Feature
• [ ] Bug

[neoddish]

We do need to write the docs in two languages.

We tried to use customized tags, such as inline tag {@cn ...} for Chinese version and {@en ...} for English version. The code would be like this:

/**
 * {@cn 分析单个字段的类型}
 * {@en Type analyzer for a single field}
 *
 * @remarks
 * {@cn 如果数据的值只有两种会被认为是`boolean`值}{@en It will be recognized as `boolean` if it consists of only two kinds of values.}
 *
 *
 * @param array - {@cn 数据列表}{@en data list}
 * @param size - {@cn 选取的样本个数}{@en size of sample}
 * @returns {@cn 字段信息}{@en field info}
 *
 * @public
 */

But it seems that inline tags could not be nested. For example, {@en This is a {@Link field | www.whatisfield.com}...}

So, we modified the rules a little bit. One @lang tag followed by a parameter cn or en (or other languages)...

/**
 * @lang cn 分析单个{@link 字段 | www.whatisfield.com}的类型
 * @lang en Type analyzer for a single {@link field | www.whatisfield.com}
 *
 * @remarks
 * @lang cn 如果数据的值只有两种会被认为是`boolean`值
 * @lang en It will be recognized as `boolean` if it consists of only two kinds of values.
 *
 * @param array - @lang cn 数据列表 @lang en data list
 * @param size - @lang cn 选取的样本个数 @lang en size of sample
 * @returns @lang cn 字段信息 @lang en field info
 *
 * @public
 */

While extracting the api, we assign the language first, like lang=cn, then only the contents in the @lang cn will be extracted.

This is just an assumptive workaround, maybe we can have better solution?

[octogonz]

This question applies to TSDoc as much as to API Extractor. It was previously discussed here: https://github.com/microsoft/tsdoc/issues/153

My thinking is that the doc comments should contain only the primary language, and then the other languages should be managed via data files. One reason is that it would be cumbersome to clutter up the source code with translations for 50+ languages. Another reason is that the other languages are normally produced by human/machine translators, whose workflow should probably be separate from the development team. The other thread gives more details.