add proposed return type to gettext functions, event if it is already present in the global types

Author: Totto16

packages/gnome-shell/src/extensions/sharedInternals.d.ts

@@ -4,6 +4,12 @@ import type { Extension } from './extension.js';
 import type Gio from '@girs/gio-2.0';
 import type GObject from '@girs/gobject-2.0';
 
+/**
+ * @see https://gjs.guide/extensions/development/translations.html#marking-strings-for-translation
+ * @notes in Gnome Shell every string has format, since String.prototype.format() is added by it, but the best practices state, that only gettext functions use that, we already have that types in  "global.d.ts" but if you don't want to have that type on every string, it is the return type of all those functions without importing the global types 
+ */
+export type FormattableString = string & { format: (...args: any[]) => string };
+
 export interface TranslationFunctions {
     /**
      * Translate `str` using the extension's gettext domain
@@ -12,7 +18,7 @@ export interface TranslationFunctions {
      *
      * @returns {string} the translated string
      */
-    gettext(str: string): string
+    gettext(str: string): FormattableString;
     /**
      * Translate `str` and choose plural form using the extension's
      * gettext domain
@@ -23,7 +29,7 @@ export interface TranslationFunctions {
      *
      * @returns {string} the translated string
      */
-    ngettext(str: string, strPlural: string, n: number): string
+    ngettext(str: string, strPlural: string, n: number): FormattableString;
 
     /**
      * Translate `str` in the context of `context` using the extension's
@@ -34,38 +40,38 @@ export interface TranslationFunctions {
      *
      * @returns {string} the translated string
      */
-    pgettext(context: string, str: string): string
+    pgettext(context: string, str: string): FormattableString;
 }
 
 export class ExtensionBase {
     #gettextDomain: string | null;
 
-    readonly metadata: ExtensionMetadata
+    readonly metadata: ExtensionMetadata;
 
     /**
      * Look up an extension by URL (usually 'import.meta.url')
      *
      * @param url - a file:// URL
      */
-    static lookupByURL(url: string): Extension | null
+    static lookupByURL(url: string): Extension | null;
 
     /**
      * Look up an extension by UUID
      *
      * @param {string} _uuid
      */
-    static lookupByUUID(_uuid: string): Extension | null
+    static lookupByUUID(_uuid: string): Extension | null;
 
     /**
      * @param metadata - metadata passed in when loading the extension
      */
-    constructor(metadata: ExtensionMetadata)
+    constructor(metadata: ExtensionMetadata);
 
-    get uuid(): string
+    get uuid(): string;
 
-    get dir(): Gio.File
+    get dir(): Gio.File;
 
-    get path(): string
+    get path(): string;
 
     /**
      * Get a GSettings object for schema, using schema files in
@@ -76,7 +82,7 @@ export class ExtensionBase {
      *
      * @returns {}
      */
-    getSettings(schema?: string): Gio.Settings
+    getSettings(schema?: string): Gio.Settings;
 
     /**
      * Initialize Gettext to load translations from extensionsdir/locale. If
@@ -85,7 +91,7 @@ export class ExtensionBase {
      *
      * @param {string=} domain - the gettext domain to use
      */
-    initTranslations(domain: string): void
+    initTranslations(domain: string): void;
 
     /**
      * Translate `str` using the extension's gettext domain
@@ -94,7 +100,7 @@ export class ExtensionBase {
      *
      * @returns the translated string
      */
-    gettext(str: string): string
+    gettext(str: string): FormattableString;
 
     /**
      * Translate `str` and choose plural form using the extension's
@@ -106,7 +112,7 @@ export class ExtensionBase {
      *
      * @returns {string} the translated string
      */
-    ngettext(str: string, strPlural: string, n: number): string
+    ngettext(str: string, strPlural: string, n: number): FormattableString;
 
     /**
      * Translate `str` in the context of `context` using the extension's
@@ -117,29 +123,29 @@ export class ExtensionBase {
      *
      * @returns {string} the translated string
      */
-    pgettext(context: string, str: string): string
+    pgettext(context: string, str: string): FormattableString;
 
     /**
      * @param {string} func
      */
-    #checkGettextDomain(func: string)
+    #checkGettextDomain(func: string);
 }
 
 export class GettextWrapper {
     #url: string | null;
     #extensionClass: ExtensionBase;
 
-    constructor(extensionClass: ExtensionBase, url: string)
+    constructor(extensionClass: ExtensionBase, url: string);
 
-    #detectUrl(): string | null
+    #detectUrl(): string | null;
 
-    #lookupExtension(funcName: string): ExtensionBase
+    #lookupExtension(funcName: string): ExtensionBase;
 
-    #gettext(str: string): string
+    #gettext(str: string): FormattableString;
 
-    #ngettext(str: string, strPlural: string, n: number): string
+    #ngettext(str: string, strPlural: string, n: number): FormattableString;
 
-    #pgettext(context:any, str: string): string
+    #pgettext(context: any, str: string): FormattableString;
 
-    defineTranslationFunctions(): TranslationFunctions
+    defineTranslationFunctions(): TranslationFunctions;
 }