docs: fix and improve localization docs (v13 backport) (#7807)

src/structures/ApplicationCommand.js

@@ -65,7 +65,7 @@ class ApplicationCommand extends Base {
     if ('name_localizations' in data) {
       /**
        * The name localizations for this command
-       * @type {?Object<string, string>}
+       * @type {?Object<Locale, string>}
        */
       this.nameLocalizations = data.name_localizations;
     } else {
@@ -75,7 +75,7 @@ class ApplicationCommand extends Base {
     if ('name_localized' in data) {
       /**
        * The localized name for this command
-       * @type {?Object<string, string>}
+       * @type {?string}
        */
       this.nameLocalized = data.name_localized;
     } else {
@@ -93,7 +93,7 @@ class ApplicationCommand extends Base {
     if ('description_localizations' in data) {
       /**
        * The description localizations for this command
-       * @type {?string}
+       * @type {?Object<Locale, string>}
        */
       this.descriptionLocalizations = data.description_localizations;
     } else {
@@ -168,9 +168,9 @@ class ApplicationCommand extends Base {
    * Data for creating or editing an application command.
    * @typedef {Object} ApplicationCommandData
    * @property {string} name The name of the command
-   * @property {Object<string, string>} [nameLocalizations] The localizations for the command name
+   * @property {Object<Locale, string>} [nameLocalizations] The localizations for the command name
    * @property {string} description The description of the command
-   * @property {Object<string, string>} [descriptionLocalizations] The localizations for the command description
+   * @property {Object<Locale, string>} [descriptionLocalizations] The localizations for the command description
    * @property {ApplicationCommandType} [type] The type of the command
    * @property {ApplicationCommandOptionData[]} [options] Options for the command
    * @property {boolean} [defaultPermission] Whether the command is enabled by default when the app is added to a guild
@@ -185,9 +185,9 @@ class ApplicationCommand extends Base {
    * @typedef {Object} ApplicationCommandOptionData
    * @property {ApplicationCommandOptionType|number} type The type of the option
    * @property {string} name The name of the option
-   * @property {Object<string, string>} [nameLocalizations] The name localizations for the option
+   * @property {Object<Locale, string>} [nameLocalizations] The name localizations for the option
    * @property {string} description The description of the option
-   * @property {Object<string, string>} [descriptionLocalizations] The description localizations for the option
+   * @property {Object<Locale, string>} [descriptionLocalizations] The description localizations for the option
    * @property {boolean} [autocomplete] Whether the option is an autocomplete option
    * @property {boolean} [required] Whether the option is required
    * @property {ApplicationCommandOptionChoiceData[]} [choices] The choices of the option for the user to pick from
@@ -201,15 +201,10 @@ class ApplicationCommand extends Base {
   /**
    * @typedef {Object} ApplicationCommandOptionChoiceData
    * @property {string} name The name of the choice
-   * @property {Object<string, string>} [nameLocalizations] The localized names for this choice
+   * @property {Object<Locale, string>} [nameLocalizations] The localized names for this choice
    * @property {string|number} value The value of the choice
    */
 
-  /**
-   * @typedef {ApplicationCommandOptionChoiceData} ApplicationCommandOptionChoice
-   * @property {string} [nameLocalized] The localized name for this choice
-   */
-
   /**
    * Edits this application command.
    * @param {ApplicationCommandData} data The data to update the command with
@@ -237,7 +232,7 @@ class ApplicationCommand extends Base {
 
   /**
    * Edits the localized names of this ApplicationCommand
-   * @param {Object<string, string>} nameLocalizations The new localized names for the command
+   * @param {Object<Locale, string>} nameLocalizations The new localized names for the command
    * @returns {Promise<ApplicationCommand>}
    * @example
    * // Edit the name localizations of this command
@@ -263,7 +258,7 @@ class ApplicationCommand extends Base {
 
   /**
    * Edits the localized descriptions of this ApplicationCommand
-   * @param {Object<string, string>} descriptionLocalizations The new localized descriptions for the command
+   * @param {Object<Locale, string>} descriptionLocalizations The new localized descriptions for the command
    * @returns {Promise<ApplicationCommand>}
    * @example
    * // Edit the description localizations of this command
@@ -449,6 +444,15 @@ class ApplicationCommand extends Base {
    * @property {number} [maxValue] The maximum value for an `INTEGER` or `NUMBER` option
    */
 
+  /**
+   * A choice for an application command option.
+   * @typedef {Object} ApplicationCommandOptionChoice
+   * @property {string} name The name of the choice
+   * @property {?string} nameLocalized The localized name of the choice in the provided locale, if any
+   * @property {?Object<string, string>} [nameLocalizations] The localized names for this choice
+   * @property {string|number} value The value of the choice
+   */
+
   /**
    * Transforms an {@link ApplicationCommandOptionData} object into something that can be used with the API.
    * @param {ApplicationCommandOptionData|ApplicationCommandOption} option The option to transform

src/structures/Guild.js

@@ -411,7 +411,7 @@ class Guild extends AnonymousGuild {
     if ('preferred_locale' in data) {
       /**
        * The preferred locale of the guild, defaults to `en-US`
-       * @type {string}
+       * @type {Locale}
        * @see {@link https://discord.com/developers/docs/reference#locales}
        */
       this.preferredLocale = data.preferred_locale;

src/structures/Interaction.js

@@ -76,15 +76,50 @@ class Interaction extends Base {
     this.memberPermissions = data.member?.permissions ? new Permissions(data.member.permissions).freeze() : null;
 
     /**
-     * The locale of the user who invoked this interaction
+     * A Discord locale string, possible values are:
-     * @type {string}
+     * * en-US (English, US)
+     * * en-GB (English, UK)
+     * * bg (Bulgarian)
+     * * zh-CN (Chinese, China)
+     * * zh-TW (Chinese, Taiwan)
+     * * hr (Croatian)
+     * * cs (Czech)
+     * * da (Danish)
+     * * nl (Dutch)
+     * * fi (Finnish)
+     * * fr (French)
+     * * de (German)
+     * * el (Greek)
+     * * hi (Hindi)
+     * * hu (Hungarian)
+     * * it (Italian)
+     * * ja (Japanese)
+     * * ko (Korean)
+     * * lt (Lithuanian)
+     * * no (Norwegian)
+     * * pl (Polish)
+     * * pt-BR (Portuguese, Brazilian)
+     * * ro (Romanian, Romania)
+     * * ru (Russian)
+     * * es-ES (Spanish)
+     * * sv-SE (Swedish)
+     * * th (Thai)
+     * * tr (Turkish)
+     * * uk (Ukrainian)
+     * * vi (Vietnamese)
      * @see {@link https://discord.com/developers/docs/reference#locales}
+     * @typedef {string} Locale
+     */
+
+    /**
+     * The locale of the user who invoked this interaction
+     * @type {Locale}
      */
     this.locale = data.locale;
 
     /**
      * The preferred locale from the guild this interaction was sent in
-     * @type {?string}
+     * @type {?Locale}
      */
     this.guildLocale = data.guild_locale ?? null;
   }

typings/index.d.ts

@@ -3923,10 +3923,6 @@ export interface ApplicationCommandOptionChoiceData {
   value: string | number;
 }
 
-export interface ApplicationCommandOptionChoice extends ApplicationCommandOptionChoiceData {
-  nameLocalized?: string;
-}
-
 export type ApplicationCommandType = keyof typeof ApplicationCommandTypes;
 
 export type ApplicationCommandOptionType = keyof typeof ApplicationCommandOptionTypes;