diff --git a/DisCatSharp.Docs/articles/application_commands/translations/reference.md b/DisCatSharp.Docs/articles/application_commands/translations/reference.md index c729d1932..a3f752660 100644 --- a/DisCatSharp.Docs/articles/application_commands/translations/reference.md +++ b/DisCatSharp.Docs/articles/application_commands/translations/reference.md @@ -1,110 +1,114 @@ --- uid: application_commands_translations_reference title: Translation Reference --- # Translation Reference > [!NOTE] > DisCatSharp uses [JSON](https://www.json.org) to inject the translations of [Application Commands](https://discord.com/developers/docs/interactions/application-commands). ## Command Object | Key | Value | Description | | ------------------------ | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | name | string | name of the application command | +| description? | string | description of the application command | | type | int | [type](#application-command-type) of application command, used to map command types | | name_translations | array of [Translation KVPs](#translation-kvp) | array of translation key-value-pairs for the application command name | | description_translations | array of [Translation KVPs](#translation-kvp) | array of translation key-value-pairs for the application command description, only valid for slash commands | | options | array of [Option Objects](#option-object) | array of option objects containing translations | ### Application Command Type | Type | Value | | ---------------------------- | ----- | | Slash Command | 1 | | User Context Menu Command | 2 | | Message Context Menu Command | 3 | ## Command Group Object | Key | Value | Description | | ------------------------ | --------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | name | string | name of the application command group | +| description? | string | description of the application command group | | name_translations | array of [Translation KVPs](#translation-kvp) | array of translation key-value-pairs for the application command group name | | description_translations | array of [Translation KVPs](#translation-kvp) | array of translation key-value-pairs for the application command group description | | commands | array of [Command Objects](#command-object) | array of command objects containing translations | | groups | array of [Sub Command Group Objects](#sub-command-group-object) | array of sub command group objects containing translations | ## Sub Command Group Object | Key | Value | Description | | ------------------------ | --------------------------------------------- | -------------------------------------------------------------------------------------- | | name | string | name of the application command sub group | +| description? | string | description of the application command group | | name_translations | array of [Translation KVPs](#translation-kvp) | array of translation key-value-pairs for the application command sub group name | | description_translations | array of [Translation KVPs](#translation-kvp) | array of translation key-value-pairs for the application command sub group description | | commands | array of [Command Objects](#command-object) | array of command objects containing translations | ## Option Object | Key | Value | Description | | ------------------------ | ------------------------------------------------------- | ----------------------------------------------------------------------------------- | | name | string | name of the application command option | +| description? | string | description of the application command group | | name_translations | array of [Translation KVPs](#translation-kvp) | array of translation key-value-pairs for the application command option name | | description_translations | array of [Translation KVPs](#translation-kvp) | array of translation key-value-pairs for the application command option description | | choices | array of [Option Choice Objects](#option-choice-object) | array of option choice objects containing translations | ## Option Choice Object | Key | Value | Description | | ------------------------ | --------------------------------------------- | ----------------------------------------------------------------------------------- | | name | string | name of the application command option choice | | name_translations | array of [Translation KVPs](#translation-kvp) | array of translation key-value-pairs for the application command option choice name | ## Translation KVP A translation object is a key-value-pair of `"locale": "value"`. ### Example Translation Array: ```json { "en-US": "Hello", "de": "Hallo" } ``` ## Valid Locales | Locale | Language | | ------ | --------------------- | | da | Danish | | de | German | | en-GB | English, UK | | en-US | English, US | | es-ES | Spanish | | fr | French | | hr | Croatian | | it | Italian | | lt | Lithuanian | | hu | Hungarian | | nl | Dutch | | no | Norwegian | | pl | Polish | | pt-BR | Portuguese, Brazilian | | ro | Romanian, Romania | | fi | Finnish | | sv-SE | Swedish | | vi | Vietnamese | | tr | Turkish | | cs | Czech | | el | Greek | | bg | Bulgarian | | ru | Russian | | uk | Ukrainian | | hi | Hindi | | th | Thai | | zh-CN | Chinese, China | | ja | Japanese | | zh-TW | Chinese, Taiwan | | ko | Korean | diff --git a/DisCatSharp.Docs/articles/application_commands/translations/using.md b/DisCatSharp.Docs/articles/application_commands/translations/using.md index dba6a0c9e..a346d7eec 100644 --- a/DisCatSharp.Docs/articles/application_commands/translations/using.md +++ b/DisCatSharp.Docs/articles/application_commands/translations/using.md @@ -1,197 +1,201 @@ --- uid: application_commands_translations_using title: Using Translations --- # Using Translations ## Why Do We Outsource Translation In External JSON Files Pretty simple: It's common to have translations external stored. This makes it easier to modify them, while keeping the code itself clean. ## Adding Translations Translations are added the same way like permissions are added to Application Commands: ```cs const string TRANSLATION_PATH = "translations/"; Client.GetApplicationCommands().RegisterGuildCommands(1215484634894646844, translations => { string json = File.ReadAllText(TRANSLATION_PATH + "my_command.json"); translations.AddTranslation(json); }); Client.GetApplicationCommands().RegisterGuildCommands(1215484634894646844, translations => { string json = File.ReadAllText(TRANSLATION_PATH + "my_simple_command.json"); translations.AddTranslation(json); }); ``` > [!WARNING] > If you add a translation to a class, you have to supply translations for every command in this class. Otherwise it will fail. ## Creating The Translation JSON We split the translation in two categories. One for slash command groups and one for normal slash commands and context menu commands. The `name` key in the JSON will be mapped to the command / option / choice names internally. ### Translation For Slash Command Groups Imagine, your class look like the following example: ```cs public class MyCommand : ApplicationCommandsModule { [SlashCommandGroup("my_command", "This is description of the command group.")] public class MyCommandGroup : ApplicationCommandsModule { [SlashCommand("first", "This is description of the command.")] public async Task MySlashCommand(InteractionContext context) { await context.CreateResponseAsync(InteractionResponseType.ChannelMessageWithSource, new DiscordInteractionResponseBuilder() { Content = "This is first subcommand." }); } [SlashCommand("second", "This is description of the command.")] public async Task MySecondCommand(InteractionContext context, [Option("value", "Some string value.")] string value) { await context.CreateResponseAsync(InteractionResponseType.ChannelMessageWithSource, new DiscordInteractionResponseBuilder() { Content = "This is second subcommand. The value was " + value }); } } } ``` The translation json is a object of [Command Group Objects](xref:application_commands_translations_reference#command-group-object) A correct translation json for english and german would look like that: ```json [ { "name": "my_command", "name_translations": { "en-US": "my_command", "de": "mein_befehl" }, "description_translations": { "en-US": "This is description of the command group.", "de": "Das ist die description der Befehl Gruppe." }, "commands": [ { "name": "first", "type": 1, // Type 1 for slash command "name_translations": { "en-US": "first", "de": "erste" }, "description_translations": { "en-US": "This is description of the command.", "de": "Das ist die Beschreibung des Befehls." } }, { "name": "second", "type": 1, // Type 1 for slash command "name_translations": { "en-US": "second", "de": "zweite" }, "description_translations": { "en-US": "This is description of the command.", "de": "Das ist die Beschreibung des Befehls." }, "options": [ { "name": "value", "name_translations": { "en-US": "value", "de": "wert" }, "description_translations": { "en-US": "Some string value.", "de": "Ein string Wert." } } ] } ] } ] ``` ### Translation For Slash Commands & Context Menu Commands Now imagine, that your class look like this example: ```cs public class MySimpleCommands : ApplicationCommandsModule { [SlashCommand("my_command", "This is description of the command.")] public async Task MySlashCommand(InteractionContext context) { } [ContextMenu(ApplicationCommandType.User, "My Command")] public async Task MyContextMenuCommand(ContextMenuContext context) { } } ``` The slash command is a simple [Command Object](xref:application_commands_translations_reference#command-object). Same goes for the context menu command, but note that it can't have a description. Slash Commands has the [type](xref:application_commands_translations_reference#application-command-type) `1` and context menu commands the [type](xref:application_commands_translations_reference#application-command-type) `2` or `3`. We use this to determine, where the translation belongs to. +Please note that the description field is optional. We suggest setting it for slash commands if you want to use our translation generator, which we're building right now. +Context menu commands can't have a description, so omit it. + A correct json for this example would look like that: ```json [ { "name":"my_command", + "description": "This is description of the command.", "type": 1, // Type 1 for slash command "name_translations":{ "en-US":"my_command", "de":"mein_befehl" }, "description_translations":{ "en-US":"This is description of the command.", "de":"Das ist die Beschreibung des Befehls." } }, { "name":"My Command", "type": 2, // Type 2 for user context menu command "name_translations":{ "en-US":"My Command", "de":"Mein Befehl" } } ] ``` ## Available Locales Discord has a limited choice of locales, in particular, the ones you can select in the client. To see the available locales, visit [this](xref:application_commands_translations_reference#valid-locales) page. ## Can We Get The User And Guild Locale? Yes, you can! Discord sends the user on all [interaction types](xref:DisCatSharp.InteractionType), except `Ping`. We introduced two new properties `Locale` and `GuildLocale` on [InteractionContext](xref:DisCatSharp.ApplicationCommands.Context.InteractionContext), [ContextMenuContext](xref:DisCatSharp.ApplicationCommands.Context.ContextMenuContext), [AutoCompleteContext](xref:DisCatSharp.ApplicationCommands.Context.AutocompleteContext) and [DiscordInteraction](xref:DisCatSharp.Entities.DiscordInteraction). `Locale` is the locale of the user and always represented. `GuildLocale` is only represented, when the interaction is **not** in a DM. Furthermore we cache known user locales on the [DiscordUser](xref:DisCatSharp.Entities.DiscordUser#DisCatSharp_Entities_DiscordUser_Locale) object.