From 61a44c509c40abaf7ffb95b10942889cbbf155ac Mon Sep 17 00:00:00 2001 From: Rodry <38259440+ImRodry@users.noreply.github.com> Date: Thu, 21 Apr 2022 18:07:49 +0100 Subject: [PATCH] docs(ApplicationCommand): fix and improve localization docs (#7804) --- .../src/structures/ApplicationCommand.js | 40 ++++++++++-------- packages/discord.js/src/structures/Guild.js | 3 +- .../discord.js/src/structures/Interaction.js | 41 +++++++++++++++++-- packages/discord.js/typings/index.d.ts | 4 -- 4 files changed, 61 insertions(+), 27 deletions(-) diff --git a/packages/discord.js/src/structures/ApplicationCommand.js b/packages/discord.js/src/structures/ApplicationCommand.js index df10bac40..eb83fe6dc 100644 --- a/packages/discord.js/src/structures/ApplicationCommand.js +++ b/packages/discord.js/src/structures/ApplicationCommand.js @@ -66,7 +66,7 @@ class ApplicationCommand extends Base { if ('name_localizations' in data) { /** * The name localizations for this command - * @type {?Object} + * @type {?Object} */ this.nameLocalizations = data.name_localizations; } else { @@ -76,7 +76,7 @@ class ApplicationCommand extends Base { if ('name_localized' in data) { /** * The localized name for this command - * @type {?Object} + * @type {?string} */ this.nameLocalized = data.name_localized; } else { @@ -94,7 +94,7 @@ class ApplicationCommand extends Base { if ('description_localizations' in data) { /** * The description localizations for this command - * @type {?string} + * @type {?Object} */ this.descriptionLocalizations = data.description_localizations; } else { @@ -170,9 +170,9 @@ class ApplicationCommand extends Base { * @typedef {Object} ApplicationCommandData * @property {string} name The name of the command, must be in all lowercase if type is * {@link ApplicationCommandType.ChatInput} - * @property {Object} [nameLocalizations] The localizations for the command name + * @property {Object} [nameLocalizations] The localizations for the command name * @property {string} description The description of the command, if type is {@link ApplicationCommandType.ChatInput} - * @property {Object} [descriptionLocalizations] The localizations for the command description, + * @property {Object} [descriptionLocalizations] The localizations for the command description, * if type is {@link ApplicationCommandType.ChatInput} * @property {ApplicationCommandType} [type=ApplicationCommandType.ChatInput] The type of the command * @property {ApplicationCommandOptionData[]} [options] Options for the command @@ -189,9 +189,9 @@ class ApplicationCommand extends Base { * @typedef {Object} ApplicationCommandOptionData * @property {ApplicationCommandOptionType} type The type of the option * @property {string} name The name of the option - * @property {Object} [nameLocalizations] The name localizations for the option + * @property {Object} [nameLocalizations] The name localizations for the option * @property {string} description The description of the option - * @property {Object} [descriptionLocalizations] The description localizations for the option + * @property {Object} [descriptionLocalizations] The description localizations for the option * @property {boolean} [autocomplete] Whether the autocomplete interaction is enabled for a * {@link ApplicationCommandOptionType.String}, {@link ApplicationCommandOptionType.Integer} or * {@link ApplicationCommandOptionType.Number} option @@ -209,15 +209,10 @@ class ApplicationCommand extends Base { /** * @typedef {Object} ApplicationCommandOptionChoiceData * @property {string} name The name of the choice - * @property {Object} [nameLocalizations] The localized names for this choice + * @property {Object} [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 @@ -245,7 +240,7 @@ class ApplicationCommand extends Base { /** * Edits the localized names of this ApplicationCommand - * @param {Object} nameLocalizations The new localized names for the command + * @param {Object} nameLocalizations The new localized names for the command * @returns {Promise} * @example * // Edit the name localizations of this command @@ -271,11 +266,11 @@ class ApplicationCommand extends Base { /** * Edits the localized descriptions of this ApplicationCommand - * @param {Object} descriptionLocalizations The new localized descriptions for the command + * @param {Object} descriptionLocalizations The new localized descriptions for the command * @returns {Promise} * @example * // Edit the description localizations of this command - * command.setLocalizedDescriptions({ + * command.setDescriptionLocalizations({ * 'en-GB': 'A test command', * 'pt-BR': 'Um comando de teste', * }) @@ -456,10 +451,10 @@ class ApplicationCommand extends Base { * @typedef {Object} ApplicationCommandOption * @property {ApplicationCommandOptionType} type The type of the option * @property {string} name The name of the option - * @property {Object} [nameLocalizations] The localizations for the option name + * @property {Object} [nameLocalizations] The localizations for the option name * @property {string} [nameLocalized] The localized name for this option * @property {string} description The description of the option - * @property {Object} [descriptionLocalizations] The localizations for the option description + * @property {Object} [descriptionLocalizations] The localizations for the option description * @property {string} [descriptionLocalized] The localized description for this option * @property {boolean} [required] Whether the option is required * @property {boolean} [autocomplete] Whether the autocomplete interaction is enabled for a @@ -475,6 +470,15 @@ class ApplicationCommand extends Base { * {@link ApplicationCommandOptionType.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} [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 diff --git a/packages/discord.js/src/structures/Guild.js b/packages/discord.js/src/structures/Guild.js index 3c694aef2..5bcf15f9c 100644 --- a/packages/discord.js/src/structures/Guild.js +++ b/packages/discord.js/src/structures/Guild.js @@ -336,8 +336,7 @@ class Guild extends AnonymousGuild { if ('preferred_locale' in data) { /** * The preferred locale of the guild, defaults to `en-US` - * @type {string} - * @see {@link https://discord.com/developers/docs/reference#locales} + * @type {Locale} */ this.preferredLocale = data.preferred_locale; } diff --git a/packages/discord.js/src/structures/Interaction.js b/packages/discord.js/src/structures/Interaction.js index d4640a194..0422f6e0f 100644 --- a/packages/discord.js/src/structures/Interaction.js +++ b/packages/discord.js/src/structures/Interaction.js @@ -78,15 +78,50 @@ class Interaction extends Base { : null; /** - * The locale of the user who invoked this interaction - * @type {string} + * A Discord locale string, possible values are: + * * 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; } diff --git a/packages/discord.js/typings/index.d.ts b/packages/discord.js/typings/index.d.ts index 81091b8b7..fac3b984f 100644 --- a/packages/discord.js/typings/index.d.ts +++ b/packages/discord.js/typings/index.d.ts @@ -3605,10 +3605,6 @@ export interface ApplicationCommandOptionChoiceData { value: string | number; } -export interface ApplicationCommandOptionChoice extends ApplicationCommandOptionChoiceData { - nameLocalized?: string; -} - export interface ApplicationCommandPermissionData { id: Snowflake; type: ApplicationCommandPermissionType;