Update I18N to allow use of tag names, and add flag strings

CHANGELOG.md

@@ -97,6 +97,7 @@
 -   @HarelM
 -   @kraenhansen
 -   @Nil2000
+-   @steve02081504
 -   @tristanzander
 
 # Unreleased

eslint.config.mjs

@@ -73,6 +73,11 @@ const config = {
         "@typescript-eslint/no-confusing-void-expression": "off",
         "@typescript-eslint/unbound-method": "off",
 
+        "@typescript-eslint/prefer-literal-enum-member": [
+            "error",
+            { allowBitwiseExpressions: true },
+        ],
+
         // I'd like to have this turned on, but haven't figured out how to tell it about
         // checks that are correctly linted as unnecessary for TypeDoc's usage, but not
         // for plugin permitted usage.

src/lib/converter/plugins/ImplementsPlugin.ts

@@ -5,6 +5,7 @@ import {
     DeclarationReflection,
     type ProjectReflection,
     type Reflection,
+    ReflectionFlag,
     ReflectionKind,
     SignatureReflection,
 } from "../../models/reflections/index";
@@ -405,7 +406,7 @@ function createLink(
     clause: ts.HeritageClause,
     expr: ts.ExpressionWithTypeArguments,
     symbol: ts.Symbol,
-    isOverwrite: boolean,
+    isInherit: boolean,
 ) {
     const project = context.project;
     const name = `${expr.expression.getText()}.${getHumanName(symbol.name)}`;
@@ -435,7 +436,8 @@ function createLink(
             return;
         }
 
-        if (isOverwrite) {
+        if (isInherit) {
+            target.setFlag(ReflectionFlag.Inherited);
             target.inheritedFrom ??= ReferenceType.createBrokenReference(
                 name,
                 project,

src/lib/internationalization/internationalization.ts

@@ -8,6 +8,7 @@ import {
 import { readdirSync } from "fs";
 import { join } from "path";
 import { ReflectionKind } from "../models/reflections/kind";
+import { ReflectionFlag } from "../models";
 
 /**
  * ### What is translatable?
@@ -115,7 +116,7 @@ export class Internationalization {
      * Get the translation of the specified key, replacing placeholders
      * with the arguments specified.
      */
-    translate<T extends keyof TranslatableStrings>(
+    translate<T extends keyof typeof translatable>(
         key: T,
         ...args: TranslatableStrings[T]
     ): TranslatedString {
@@ -233,6 +234,54 @@ export class Internationalization {
         }
     }
 
+    flagString(flag: ReflectionFlag): TranslatedString {
+        switch (flag) {
+            case ReflectionFlag.None:
+                throw new Error("Should be unreachable");
+            case ReflectionFlag.Private:
+                return this.proxy.flag_private();
+            case ReflectionFlag.Protected:
+                return this.proxy.flag_protected();
+            case ReflectionFlag.Public:
+                return this.proxy.flag_public();
+            case ReflectionFlag.Static:
+                return this.proxy.flag_static();
+            case ReflectionFlag.External:
+                return this.proxy.flag_external();
+            case ReflectionFlag.Optional:
+                return this.proxy.flag_optional();
+            case ReflectionFlag.Rest:
+                return this.proxy.flag_rest();
+            case ReflectionFlag.Abstract:
+                return this.proxy.flag_abstract();
+            case ReflectionFlag.Const:
+                return this.proxy.flag_const();
+            case ReflectionFlag.Readonly:
+                return this.proxy.flag_readonly();
+            case ReflectionFlag.Inherited:
+                return this.proxy.flag_inherited();
+        }
+    }
+
+    translateTagName(tag: `@${string}`): TranslatedString {
+        const tagName = tag.substring(1);
+        const translations = this.allTranslations.get(
+            this.application?.lang ?? "en",
+        );
+        if (translations.has(`tag_${tagName}`)) {
+            return translations.get(`tag_${tagName}`) as TranslatedString;
+        }
+        // In English, the tag names are the translated names, once turned
+        // into title case.
+        return (tagName.substring(0, 1).toUpperCase() +
+            tagName
+                .substring(1)
+                .replace(
+                    /[a-z][A-Z]/g,
+                    (x) => `${x[0]} ${x[1]}`,
+                )) as TranslatedString;
+    }
+
     /**
      * Add translations for a string which will be displayed to the user.
      */

src/lib/internationalization/locales/jp.cts

@@ -442,6 +442,10 @@ export = buildIncompleteTranslation({
     kind_plural_type_alias: "型エイリアス",
     kind_plural_reference: "リファレンス",
     kind_plural_document: "ドキュメント",
+    flag_protected: "保護",
+    flag_private: "非公開",
+    flag_external: "外部",
+    flag_inherited: "継承",
     theme_implements: "実装",
     theme_indexable: "インデックス可能",
     theme_type_declaration: "型宣言",
@@ -461,10 +465,6 @@ export = buildIncompleteTranslation({
     theme_search_index_not_available: "検索インデックスは利用できません",
     theme_settings: "テーマ設定",
     theme_member_visibility: "メンバーの可視性",
-    theme_member_protected: "保護",
-    theme_member_private: "非公開",
-    theme_member_external: "外部",
-    theme_member_inherited: "継承",
     theme_theme: "配色",
     theme_os: "自動",
     theme_light: "ライト",
@@ -476,5 +476,4 @@ export = buildIncompleteTranslation({
     tag_see: "参照",
     tag_group: "所属グループ",
     tag_example: "例",
-    tag_alias: "別名",
 });

src/lib/internationalization/locales/zh.cts

@@ -369,6 +369,10 @@ export = buildIncompleteTranslation({
     kind_plural_type_alias: "类型别名",
     kind_plural_reference: "参考",
     kind_plural_document: "文档",
+    flag_protected: "受保护",
+    flag_private: "私有",
+    flag_external: "外部",
+    flag_inherited: "继承",
     theme_implements: "实现",
     theme_indexable: "可索引",
     theme_type_declaration: "类型声明",
@@ -388,10 +392,6 @@ export = buildIncompleteTranslation({
     theme_search_index_not_available: "搜索索引不可用",
     theme_settings: "显示设置",
     theme_member_visibility: "成员可见性",
-    theme_member_protected: "受保护",
-    theme_member_private: "私有",
-    theme_member_external: "外部",
-    theme_member_inherited: "继承",
     theme_theme: "配色",
     theme_os: "自动",
     theme_light: "浅色",
@@ -403,5 +403,4 @@ export = buildIncompleteTranslation({
     tag_see: "参阅",
     tag_group: "所属分组",
     tag_example: "示例",
-    tag_alias: "别名",
 });

src/lib/internationalization/translatable.ts

@@ -1,3 +1,9 @@
+import type {
+    blockTags,
+    inlineTags,
+    modifierTags,
+} from "../utils/options/tsdoc-defaults";
+
 export function buildTranslation<
     T extends BuiltinTranslatableStringConstraints,
 >(translations: T) {
@@ -430,6 +436,19 @@ export const translatable = {
     kind_plural_reference: "References",
     kind_plural_document: "Documents",
 
+    // ReflectionFlag translations
+    flag_private: "Private",
+    flag_protected: "Protected",
+    flag_public: "Public",
+    flag_static: "Static",
+    flag_external: "External",
+    flag_optional: "Optional",
+    flag_rest: "Rest",
+    flag_abstract: "Abstract",
+    flag_const: "Const",
+    flag_readonly: "Readonly",
+    flag_inherited: "Inherited",
+
     // ==================================================================
     // Strings that show up in the default theme
     // ==================================================================
@@ -471,7 +490,15 @@ export type BuiltinTranslatableStringArgs = {
     [K in keyof typeof translatable]: BuildTranslationArguments<
         (typeof translatable)[K]
     >;
-};
+} & Record<
+
+        | (typeof blockTags)[number]
+        | (typeof inlineTags)[number]
+        | (typeof modifierTags)[number] extends `@${infer T}`
+        ? `tag_${T}`
+        : never,
+    []
+>;
 
 type BuildTranslationArguments<
     T extends string,

src/lib/models/reflections/abstract.ts

@@ -8,6 +8,10 @@ import type { ReflectionVariant } from "./variant";
 import type { DeclarationReflection } from "./declaration";
 import type { DocumentReflection } from "./document";
 import { NonEnumerable } from "../../utils/general";
+import type {
+    Internationalization,
+    TranslatedString,
+} from "../../internationalization";
 
 /**
  * Current reflection id.
@@ -25,28 +29,24 @@ export function resetReflectionID() {
 
 export enum ReflectionFlag {
     None = 0,
-    Private = 1,
-    Protected = 2,
-    Public = 4,
-    Static = 8,
-    ExportAssignment = 16,
-    External = 32,
-    Optional = 64,
-    DefaultValue = 128,
-    Rest = 256,
-    Abstract = 512,
-    Const = 1024,
-    Let = 2048,
-    Readonly = 4096,
+    Private = 1 << 0,
+    Protected = 1 << 1,
+    Public = 1 << 2,
+    Static = 1 << 3,
+    External = 1 << 4,
+    Optional = 1 << 5,
+    Rest = 1 << 6,
+    Abstract = 1 << 7,
+    Const = 1 << 8,
+    Readonly = 1 << 9,
+    Inherited = 1 << 10,
 }
 
 const relevantFlags: ReflectionFlag[] = [
     ReflectionFlag.Private,
     ReflectionFlag.Protected,
     ReflectionFlag.Static,
-    ReflectionFlag.ExportAssignment,
     ReflectionFlag.Optional,
-    ReflectionFlag.DefaultValue,
     ReflectionFlag.Rest,
     ReflectionFlag.Abstract,
     ReflectionFlag.Const,
@@ -56,7 +56,7 @@ const relevantFlags: ReflectionFlag[] = [
 /**
  * This must extend Array in order to work with Handlebar's each helper.
  */
-export class ReflectionFlags extends Array<string> {
+export class ReflectionFlags {
     private flags = ReflectionFlag.None;
 
     hasFlag(flag: ReflectionFlag) {
@@ -114,10 +114,6 @@ export class ReflectionFlags extends Array<string> {
         return this.hasFlag(ReflectionFlag.Rest);
     }
 
-    get hasExportAssignment(): boolean {
-        return this.hasFlag(ReflectionFlag.ExportAssignment);
-    }
-
     get isAbstract(): boolean {
         return this.hasFlag(ReflectionFlag.Abstract);
     }
@@ -130,6 +126,10 @@ export class ReflectionFlags extends Array<string> {
         return this.hasFlag(ReflectionFlag.Readonly);
     }
 
+    get isInherited() {
+        return this.hasFlag(ReflectionFlag.Inherited);
+    }
+
     setFlag(flag: ReflectionFlag, set: boolean) {
         switch (flag) {
             case ReflectionFlag.Private:
@@ -158,20 +158,20 @@ export class ReflectionFlags extends Array<string> {
         }
     }
 
+    getFlagStrings(i18n: Internationalization) {
+        const strings: TranslatedString[] = [];
+        for (const flag of relevantFlags) {
+            if (this.hasFlag(flag)) {
+                strings.push(i18n.flagString(flag));
+            }
+        }
+        return strings;
+    }
+
     private setSingleFlag(flag: ReflectionFlag, set: boolean) {
-        const name = ReflectionFlag[flag].replace(
-            /(.)([A-Z])/g,
-            (_m, a: string, b: string) => a + " " + b.toLowerCase(),
-        );
         if (!set && this.hasFlag(flag)) {
-            if (relevantFlags.includes(flag)) {
-                this.splice(this.indexOf(name), 1);
-            }
             this.flags ^= flag;
         } else if (set && !this.hasFlag(flag)) {
-            if (relevantFlags.includes(flag)) {
-                this.push(name);
-            }
             this.flags |= flag;
         }
     }
@@ -184,10 +184,10 @@ export class ReflectionFlags extends Array<string> {
         "isExternal",
         "isOptional",
         "isRest",
-        "hasExportAssignment",
         "isAbstract",
         "isConst",
         "isReadonly",
+        "isInherited",
     ] as const;
 
     toObject(): JSONOutput.ReflectionFlags {

src/lib/output/themes/default/DefaultTheme.tsx

@@ -498,7 +498,7 @@ function getReflectionClasses(
     // partials/navigation.tsx.
     for (const key of Object.keys(filters)) {
         if (key === "inherited") {
-            if (reflection.isDeclaration() && reflection.inheritedFrom) {
+            if (reflection.flags.isInherited) {
                 classes.push("tsd-is-inherited");
             }
         } else if (key === "protected") {

src/lib/output/themes/default/partials/comment.tsx

@@ -1,7 +1,6 @@
 import type { DefaultThemeRenderContext } from "../DefaultThemeRenderContext";
 import { JSX, Raw } from "../../../../utils";
 import { type Reflection, ReflectionKind } from "../../../../models";
-import { camelToTitleCase } from "../../lib";
 import { anchorIcon } from "./anchor-icon";
 
 // Note: Comment modifiers are handled in `renderFlags`
@@ -32,8 +31,8 @@ export function commentTags(context: DefaultThemeRenderContext, props: Reflectio
             <div class="tsd-comment tsd-typography">
                 {tags.map((item) => {
                     const name = item.name
-                        ? `${camelToTitleCase(item.tag.substring(1))}: ${item.name}`
-                        : camelToTitleCase(item.tag.substring(1));
+                        ? `${context.internationalization.translateTagName(item.tag)}: ${item.name}`
+                        : context.internationalization.translateTagName(item.tag);
 
                     const anchor = props.getUniqueAliasInPage(name);
 
@@ -56,12 +55,12 @@ export function commentTags(context: DefaultThemeRenderContext, props: Reflectio
 
 const flagsNotRendered: `@${string}`[] = ["@showCategories", "@showGroups", "@hideCategories", "@hideGroups"];
 
-export function reflectionFlags(_context: DefaultThemeRenderContext, props: Reflection) {
-    const allFlags = [...props.flags];
+export function reflectionFlags(context: DefaultThemeRenderContext, props: Reflection) {
+    const allFlags = props.flags.getFlagStrings(context.internationalization);
     if (props.comment) {
         for (const tag of props.comment.modifierTags) {
             if (!flagsNotRendered.includes(tag)) {
-                allFlags.push(camelToTitleCase(tag.substring(1)));
+                allFlags.push(context.internationalization.translateTagName(tag));
             }
         }
     }