Tsdoc: How to localize TSDoc content?

[xiaoxiangmoe]

export interface IField {
  /**
   * @language-tag en-US
   * @description name of fields
   */
  /**
   * @language-tag zh-Hans-CN
   * @description 字段名
   */
  name: string;
}

it will help us to generate documents for multi language.

We can found language tags rfc in Tags for Identifying Languages and search tag in IANA Language Subtag Registry

[DiamondYuan]

export interface IField {
  /**
   * @locale en-US
   * @description name of fields
   */
  /**
   * @locale zh-CN
   * @description 字段名
   */
  name: string;
}

locale maybe better ?

[octogonz]

I think there may be problems with splitting content across multiple comment blocks. Many TSDoc tags are independent of a particular locale, for example: @eventProperty, @internal, @readonly, @virtual. We would need to designate one of the comment blocks to be the "main" one that gets the locale-neutral information.

I'll also point out that companies that get involved with localization frequently need to support many more than 2 locales. Microsoft products support around 50. This approach get become awkward if we had 50 comment blocks next to each property in the source code.

Lastly, although software engineers normally author the documentation content in the main locale (e.g. English), the other locales are typically handled by professional translators. Translator people are generally not software engineers, and it may be difficult for them to safely commit changes to a Git branch containing production source code.

Here's a different approach for comparison:

Suppose the source code contains TSDoc comments only in the main locale (e.g. English). And suppose that a documentation tool extracts the TypeScript API signatures and TSDoc content from the source code, and then generates an intermediary file (e.g. widget-library.en-us.json or widget-library.en-us.xml) that represents the API structure and docs. These files are sent to a translator service, who fills in content for the other 49 locales (e.g. widget-library.de-de.json or widget-library.de-de.xml). The resulting file set is then used to generate the outputs such as an API web site, localized .d.ts files, etc.

What would these files look like? Compared to normal localized strings, TSDoc is a hierarchical rich text format. So it could be mapped onto nesting tags such as HTML. API Extractor 7 took the interesting approach of embedding TSDoc in the documentation .json.file, i.e. reusing the TSDoc library as a serialization/deserialization mechanism (example: api-documenter-test.api.json). This file format isn't used for localization today, but possibly it could be. If so, the @locale tag would not be needed, since the JSON file structure itself would probably already distinguish the locales. Just an idea...

[octogonz]

@dend FYI