Backport PR #10860: Fix code names showing up in new translations, add docs (#10863)

Co-authored-by: Michał Krassowski <5832902+krassowski@users.noreply.github.com>

packages/filebrowser/src/listing.ts

@@ -1523,7 +1523,7 @@ export class DirListing extends Widget {
         }
         if (!isValidFileName(newName)) {
           void showErrorMessage(
-            this._trans.__('showErrorMessage', 'Rename Error'),
+            this._trans.__('Rename Error'),
             Error(
               this._trans._p(
                 'showErrorMessage',

packages/toc-extension/schema/plugin.json

@@ -6,7 +6,7 @@
   "properties": {
     "numberingH1": {
       "title": "Enable h1 numbering",
-      "description": "Whether to number first level headings",
+      "description": "Whether to number first-level headings",
       "type": "boolean",
       "default": true
     },
@@ -18,8 +18,8 @@
     },
     "syncCollapseState": {
       "type": "boolean",
-      "title": "syncCollapseState",
-      "description": "If set to true, when a header is collapsed in the ToC the corresponding section in the notebook is collapsed as well and vice versa.",
+      "title": "Synchronize collapse state",
+      "description": "If set to true, when a header is collapsed in the table of contents the corresponding section in the notebook is collapsed as well and vice versa.",
       "default": false
     }
   },

packages/translation/src/tokens.ts

@@ -34,10 +34,48 @@ export class TranslatorConnector
   private _translationsUrl: string;
 }
 
+/**
+ * Bundle of gettext-based translation functions.
+ *
+ * The calls to the functions in this bundle will be automatically
+ * extracted by `jupyterlab-translate` package to generate translation
+ * template files if the bundle is assigned to:
+ * - variable named `trans`,
+ * - public attribute named `trans` (`this.trans`),
+ * - private attribute named `trans` (`this._trans`),
+ * - `trans` attribute `props` variable (`props.trans`),
+ * - `trans` attribute `props` attribute (`this.props.trans`)
+ */
 export type TranslationBundle = {
+  /**
+   * Alias for `gettext` (translate strings without number inflection)
+   * @param msgid message (text to translate)
+   * @param args
+   */
   __(msgid: string, ...args: any[]): string;
+  /**
+   * Alias for `ngettext` (translate accounting for plural forms)
+   * @param msgid message for singular
+   * @param msgid_plural message for plural
+   * @param n determines which plural form to use
+   * @param args
+   */
   _n(msgid: string, msgid_plural: string, n: number, ...args: any[]): string;
+  /**
+   * Alias for `pgettext` (translate in given context)
+   * @param msgctxt context
+   * @param msgid message (text to translate)
+   * @param args
+   */
   _p(msgctxt: string, msgid: string, ...args: any[]): string;
+  /**
+   * Alias for `npgettext` (translate accounting for plural forms in given context)
+   * @param msgctxt context
+   * @param msgid message for singular
+   * @param msgid_plural message for plural
+   * @param n number used to determine which plural form to use
+   * @param args
+   */
   _np(
     msgctxt: string,
     msgid: string,