Discord slash command localization QA is the process of checking that translated command names, option descriptions and choice labels appear in the right client language while the app still receives the values its code expects. Translating a Discord bot command is not the same as translating an ordinary Discord message. The visible slash command may change language; the underlying command identity, option structure and handler must continue to operate as designed.
People searching Discord application command localization, Discord name_localizations, description_localizations, discord.js slash command translation, Discord command locale fallback and how to localize Discord bot responses usually want to release a command without confusing multilingual users or breaking an interaction. This article has one reader job: validate the localized application-command contract from registration through the response a user sees. It covers developer-facing tests and plain-language review checks, not everyday chat translation.
The working rule is simple: treat presentation strings and execution identifiers as separate layers. A translated option label may tell the user “language,” “idioma” or another local equivalent, but the bot should not silently reinterpret the option name, accepted choice value, permission check or business operation. Discord’s official documentation describes localization dictionaries on commands and options, locale-based fallback behavior and interaction payloads that still use default command and option names. Those details should shape both translation and testing.
On this page
Quick answer: test what appears and what executes
Make a small command with one required option and two choices, then register supported language dictionaries in a development environment. Open the command in at least two Discord client language settings. Check the visible command label, help description, option label and choice names. Invoke the command with each choice and inspect the incoming interaction payload. The application should receive the stable default identifiers and underlying values expected by the handler, even if the display words changed. Finally, check the response itself in the intended user language.
For example, a fictional study bot has /practice topic:fractions in its default language. A Spanish client may see localized text for the command and the topic option. The option value can remain fractions, a stable machine identifier, while the reply says “Práctica de fracciones” and provides a valid exercise. A translation that changes the client-facing choice name but causes the program to receive an unexpected value has crossed the boundary between presentation and data. That is a functional defect, not merely awkward vocabulary.
Do not use visual inspection alone as the release gate. A slash command may look perfect in autocomplete yet fail after submission because the bot branches on localized display names instead of stable values. Another command may execute correctly but display the wrong choice label after a user changes language. Good QA has two screenshots or observations plus one verified interaction path: what the user selected, what the application received, and what the application returned.
Understand the three layers Discord keeps separate
The first layer is the application-command definition registered with Discord. This includes the default command name, description, option names, option descriptions, optional choice names and localization dictionaries where supported. The second layer is the client experience. Discord selects localized presentation text for the user’s language where available and applies its documented fallback behavior where not. The third layer is the interaction your application handles. It contains canonical command information and a locale indication so your app can return a properly localized response.
Problems arise when a team treats these layers as one translated string. A developer may translate a command’s default identifier directly in source code and then wonder why analytics, permission configuration or command synchronization sees a different command. A translator may replace an option’s stored choice value with a phrase intended only for users. A backend developer may route on whatever localized label appeared in a screenshot. The failure is architectural: text meant for reading has been used as a machine contract.
Build an explicit map. command_key=practice, option_key=topic, choice_value=fractions, display_name_es=practicar, choice_label_es=fracciones, response_template_es=.... The exact local wording should be reviewed by a speaker of that language, but the key/value relationship should be reviewed by a developer. If the display name changes later for readability, the stable value must not change as an accidental side effect. This division also makes rollback easier: remove one faulty language rendering without deleting the command itself.
Inventory every translatable surface before working quickly
Command localization spans more than the first visible verb after a slash. List command names and descriptions, subcommands, subcommand groups, option names and descriptions, choice names, autocomplete labels, error messages, success responses, confirmation prompts, buttons, modals and help documentation. Some of those are represented in application-command registration dictionaries, while others are constructed by your app when responding to an interaction. A single dictionary does not automatically translate every user-facing component your bot may send.
Consider /session start duration:30. A French user might see a localized description and parameter label, but a subsequent message still says “Started session for 30 minutes.” If the bot is advertised as localized, the untranslated confirmation is a partial delivery. Conversely, translating the response alone without localizing the option description leaves users guessing what the input controls. Make a surface inventory that tells each reviewer where a string originates: API command definition, application resource bundle, dynamic database value, or user-submitted content.
Pay attention to explanatory prose inside option descriptions. They may include ranges or conditions, such as “Choose a number from 5 to 120” or “Available only to moderators.” Translating the short option name while losing this constraint can cause predictable input errors. The test must compare semantic constraints, not just sentence fluency. Write a brief for each command listing what each option actually does, accepted types and required permissions, so translators do not infer behavior from the English word alone.
Work within Discord’s command naming rules
Discord documents restrictions for chat-input command and option names, including allowed character classes, lengths and lowercase behavior for cased letters. Its API also imposes character limits on descriptions and choice labels. Treat these as validation constraints that localizations must satisfy, not as a request to erase accents or transliterate every script. Native language characters can be valid where the rules permit them; punctuation and spacing choices that look natural in ordinary prose may be invalid in command identifiers.
The safe workflow is to separate a draft for linguistic review from a machine-checkable candidate. The linguist proposes a concise localized name that users will recognize. The developer validates allowed characters, uniqueness and length. If the proposal fails, both parties choose a new label rather than applying a blind character deletion that produces a confusing word. A command name is an action affordance: it should be recognizable in the target language while remaining compatible with the client syntax.
Descriptions permit natural sentences and should explain what happens, not merely repeat the command name. If a command named practice has description “Practice,” the translator has little context and the user gains little guidance. “Get a five-question quiz on a chosen topic” translates more reliably because it contains the action and outcome. Where the default description refers to a paid feature or permissions, verify that the translated claim remains true for the server and installation contexts in which the command is available.
Avoid collisions among translated option names
Discord documents extra uniqueness requirements for localized option names. This deserves special attention because two distinct English labels can collapse into one familiar target-language term. A bot might have source for the source language and origin for the source document. In another language, a translator may call both “origen.” They sound sensible independently, but the command form needs distinguishable option names. The UI and API cannot safely represent two arguments with the same local label in the same command context.
A collision check should operate on each command and locale separately. Collect the default option names, then all localized option names for the selected locale, and compare them after applying the relevant syntax constraints. Ask the translator to resolve conflicts with descriptive alternatives: “source_language” versus “source_file,” for example, if that is understandable and permissible. Do not rename the stable default keys simply to make the localized surface work. That transfers a display issue into a backend migration.
Choice names can also be confusing without being invalid. A reading bot may offer basic, standard and advanced, yet the translated labels for basic and standard may appear interchangeable to the target audience. Test by asking a new user to choose the intended level without looking at the English labels. If they cannot, the distinction should be repaired before release. A valid API payload is necessary but not sufficient for a usable multilingual command.
Keep choice display names apart from stored values
A string choice has a label shown to the user and a value sent to the application. The translated label is not necessarily the value. A bot offering practice topics might register a choice with value fractions and localized name “Fracciones.” The handler should route fractions to the fraction-question bank. If a developer updates the value to the Spanish word to make a screenshot look consistent, the English handler may no longer find the matching topic. Even worse, a program may silently fall back to an unrelated lesson while reporting success.
Use a value-preservation test: for each choice, record the canonical value before localization, register the localized names, invoke the option under the target client locale and confirm the received value is unchanged. Include integer and number choices if the app uses them. A label such as “30 minutes” must still map to the intended numeric duration; changing a local decimal punctuation convention should not turn a number into a string or a different magnitude. Validate the semantics at the point where the handler consumes the value.
Autocomplete deserves its own test because suggested choices may come from a live endpoint rather than a static registered list. The application may need to generate localized result labels dynamically while preserving stable completion values. Test partial query matching, language switching, empty states and non-ASCII search terms. Do not assume that localizing a command’s static options automatically localizes dynamic autocomplete suggestions. They belong to another response path and can fail independently.
Use default identifiers in handlers, not translated labels
Discord’s documentation notes that an interaction payload continues to use default command, subcommand and option names even when those items display localized labels in the client. Build routing and command dispatch around those canonical identifiers. This is the central reason developers can add languages without rewriting every handler. It also means a test harness that submits translated option keys directly may not reproduce a genuine client interaction correctly.
For a hypothetical bot, think of data.name === 'practice', with topic retrieved as the default option name. Your renderer can output localized response strings using the user’s locale, while business logic remains bound to practice and topic. Do not parse the English confirmation string to infer whether the operation succeeded. Return structured success or error states and then select suitable target-language copy. That keeps your core operation testable when the interface changes.
There is a second subtlety: a component click or later modal submission may occur after the initial slash command. If your app needs the preferred locale later, decide how that information will be retained or re-evaluated securely. Do not store a user’s locale as if it were a permanent identity attribute. Language preferences can change, and the interaction’s reported locale can differ from the guild’s locale. Explicitly document which signal each response uses, so two people in the same server are not forced into one language merely because a moderator configured the server in that language.
Distinguish user locale from guild locale
Discord interaction examples include both locale and guild_locale in suitable contexts. They are not interchangeable. The former tells you about the user’s selected locale for that interaction; the latter can describe the server context. A helpful bot might respond to individual commands in the user’s language even when its server-wide announcements use a language chosen by administrators. The decision depends on the communication surface and product policy. Good localization QA verifies that the bot consistently follows the chosen policy.
Suppose a student has the Discord client set to Spanish while joining an English-language study community. They invoke a private quiz command. Showing the prompt in Spanish may support comprehension; posting the same private user’s Spanish explanation into a shared moderation log could confuse staff. Define separate policies for user-facing replies, server announcements, moderator logs and stored audit data. The developer should not simply pick the first locale-like field and hope it fits every communication.
Build a matrix with user locale, guild locale, command registration scope, expected visible command, expected reply and expected logging language. Include at least one discordance case, such as an English guild with a French user. If the bot intentionally chooses guild language for public announcements, label that as a product rule instead of treating a difference from client language as a random failure. The strongest tests make the choice explicit, observable and repeatable.
Test fallback instead of assuming it means English
An incomplete localization dictionary may be valid, but missing fields can produce unexpected mixtures. Discord documents fallback behavior among certain related locales and eventually to the default. Its example notes that English variants can fall back to each other. This matters if a developer provides British spelling only for a label and assumes American users will see the default American spelling. A fallback rule may select the localized British variant instead. The test must use current platform behavior rather than a homemade assumption that every missing key goes straight to English.
Define the intended fallback chain for your app’s own response resources separately from Discord’s command-presentation fallback. A user might see a localized command name selected by Discord but receive an app-generated English reply because your response bundle lacks that locale. Those are different systems. Avoid a promise such as “all Spanish users see the Spanish app” unless both are deliberately supported. In release notes, state what has been translated and what may fall back.
A useful fallback test deletes or omits one noncritical translation in a staging command definition and observes the result under two related client locales. Document the behavior without relying on that deliberate omission in production. Then confirm that the full intended locale contains every high-value label. Partial localization is acceptable when planned, but accidental fallback on the only option that explains a payment, permission or deletion action is a serious usability defect.
Register commands safely and inspect the returned objects
Application commands can be scoped globally or to a particular guild, and registration changes should be performed through your normal authorized deployment process. Do not edit live command definitions just to conduct a copy review. Use a test app or test guild where appropriate and preserve a known-good command manifest. Discord supports commands being created, edited and overwritten through its API; an incorrect bulk overwrite can change unrelated commands, not merely the one language someone intended to update.
For each deployment, record the manifest revision, command scope, API response, expected names and localization dictionary count. Check the actual returned command object rather than assuming a successful HTTP status implies the dictionary contains every intended value. Where list endpoints return only the locale-specific localized field by default, request the full localization dictionaries using the documented query parameter when auditing the complete registration. A partial read may look as though translations vanished when they were simply not included in the response form.
After registration, wait for the client to reflect the expected command definition according to the current scope and platform behavior, then verify it from a fresh client session. A stale autocomplete entry can mislead a reviewer into blaming the wording of the latest manifest. Record screenshots with timestamps and locale settings. If the observed label does not match the command returned by the API, investigate caching or registration scope before rewriting strings that were already correct.
Build a real test manifest with controlled cases
A test manifest should be small enough to reason about but rich enough to expose mistakes. Use a command with one subcommand, one required string option, one optional integer option and a choice list. Add target-language name and description localizations for the command and options. Test the input with one normal choice, one edge-case choice and an omitted optional argument. This confirms not only that the UI translated but that requiredness and option types stayed constant.
For instance, the fictional /practice start topic:fractions count:5 command can serve a multilingual study group. The Spanish interface might use practicar, iniciar, tema, cantidad and fracciones, while code still receives practice, start, topic, count and fractions as canonical identifiers or values where applicable. Ensure the translated description still tells users that count is the number of questions, not minutes of practice. A confusing target label may invite valid but unintended numeric inputs.
Run the test with two accounts configured to different client languages rather than changing one user’s settings rapidly and trusting cached state. Record command picker text, option prompts, selected choice, interaction payload and bot response. When the result differs, identify which layer failed. Was the localization dictionary rejected or omitted? Did the Discord client choose another fallback? Did the application template engine use the wrong locale? That fault tree directs a small correction instead of a speculative rewrite of the entire command.
Translate responses as actions, not isolated prose
A localized bot response may be a confirmation, a refusal, an instruction, a warning or a request for more information. Its meaning depends on what happened in code. If the application says “Your quiz is ready,” a target-language version must not accidentally imply that a quiz was submitted or graded. If an operation requires confirmation, the copy must preserve that pending state. Buttons that say “Delete” and “Cancel” should remain distinguishable and map to the right handler identifiers, regardless of how their labels are translated.
Separate message template keys from variables and authorization decisions. For example, a result message might use quiz_completed with fields {score}, {total} and {next_action}. Translators need to know whether score and total are integers, what counts they represent and whether they can change order naturally in the sentence. Keep the variable identities intact and validate that each localized template includes the required information. The message should be evaluated on output as well as on its source resource file.
Error messages need special scrutiny. “You lack permission to manage this channel” is not equivalent to “This channel does not permit you.” One attributes a missing permission to the user; the other implies a setting of the channel. A moderation bot must not create an incorrect impression of who can perform an action. Similarly, “Try again in 10 minutes” must not become “Try ten times.” A short error text can have greater practical consequences than a long help paragraph, so it deserves specific reviewer attention.
Handle bidirectional scripts without inventing new machine semantics
Languages written from right to left introduce presentation challenges in examples mixing local text, slash commands, user mentions, punctuation and technical tokens. The local command name may use a right-to-left script while a code value, URL or user ID remains left to right. Test the actual Discord client display. Plain-text editors and screenshots can reorder segments visually, making a line appear correct in one environment and confusing in another.
Do not insert invisible direction-control characters into command identifiers as an improvisation. Such changes can affect allowed characters, search matching and copy-paste behavior. Instead, use valid localized forms and tested formatting in the response content. Where a message includes a command example, verify that users can copy and invoke the command. A beautifully typeset string that cannot be typed into the command picker is not helpful.
The reviewer should check diacritics, casing, numerals and emoji in context. A command named after a study subject may be easy to recognize in Latin script but awkward when displayed beside an Arabic question. Keep the UI label short and let the description provide necessary context. If the platform or library has specific limitations, document the tested behavior rather than claiming that all scripts will render identically on desktop and mobile.
Accessibility and discoverability are part of the contract
People discover commands through suggestions, descriptions and examples rather than by reading source code. A technically valid target label can still be poor if it is vague, indistinguishable from another option or inconsistent with the server’s help page. Put the action at the beginning of a description where possible. Prefer words that describe user outcomes over internal development terms. A pupil looking for practice questions is not helped by a localized command described as “invokes retrieval service.”
Test keyboard discovery and screen-reader output where feasible. Do labels make sense when the user cannot see the surrounding screenshot? Are options described independently, or do they depend on a visual cue such as “the button on the right”? Does the confirmation identify what was saved, deleted or sent? An interface that merely passes the API validator has not necessarily met basic accessibility goals. Translation review should ask whether the target user can understand the action before selecting it.
Documentation must also match the available command. A help page telling users to invoke /practice when their client displays /practicar may still be comprehensible, but it can create copy-paste confusion. Provide canonical identifiers and an explanation of localized labels, or generate help entries dynamically from registered command metadata where appropriate. Do not fabricate slash command strings in translated help articles without checking they are actually accepted by the platform and app registration.
Failure modes and the shortest diagnostic path
If a localized command name is missing, inspect whether the relevant localization dictionary was included in the registered command and whether the client locale has a matching entry or fallback. If the command name is visible but the description remains English, check that specific description dictionary; command and description localization can be partial independently. If two option names conflict, compare the localized names within the relevant command and locale and choose distinct alternatives without changing handler keys.
If the command executes the wrong operation, compare the submitted option values and the handler’s expected canonical values. If the action is right but the reply is in the wrong language, inspect the app-side response localization, the interaction locale field and the policy choosing user versus guild locale. If the UI differs between accounts, verify each account’s language preference and the registered scope before changing strings. These targeted checks distinguish a presentation problem, fallback issue and business-logic bug.
If command registration fails after a translation update, check syntax, length, allowed characters and collisions before blaming the network or translator. If a bulk synchronization removed unrelated commands, restore the manifest through the established deployment procedure and review the scope of the write. A disciplined release process prevents a simple language patch from becoming an outage affecting every user. Use read-only inspection and test deployments before any real update to a production app.
Case study: a study bot with a deceptive success message
A fictional bot gives a five-question mathematics quiz in English and Spanish. The developer localizes /practice and its topic choice list, but the success response is still driven by a conditional that checks whether the selected label equals the English word “Fractions.” When a Spanish user selects “Fracciones,” the UI looks right but the handler takes a generic branch and serves vocabulary questions. The bot still sends “Quiz started successfully,” so casual testers assume the feature works. A single end-to-end exercise exposes the mismatch.
The fix is to route on the stable choice value fractions, not the translated display name. Then the team translates the response template separately. The test now records Spanish command display, canonical choice value, fraction questions returned and Spanish confirmation copy. The developer also checks that the count option still means number of questions rather than elapsed time. This transforms a visually correct feature into an operationally correct one without requiring separate business logic for each language.
Next, a French user in an English-language guild sees French command text but an English public leaderboard. The team decides this is deliberate: individual quiz interactions follow user locale, while shared leaderboards follow a server language setting. The policy is documented in the test matrix. The defect report is closed only after the product owner confirms that the distinction makes sense, rather than treating every cross-language display as a random inconsistency.
Case study: an unsafe moderation command description
A moderation tool offers a command to remove a user from a temporary voice room, but not to ban that user from the server. The source description is “Remove the selected member from this voice session.” In one target language, the translation reads more like “Exclude the member from the community.” That can imply a severe disciplinary action. The actual code only disconnects the voice session, so the target description overstates the consequence and could discourage legitimate use or cause misplaced fear.
The localization reviewer rewrites the description to specify the temporary voice room and checks whether the short command name is still understandable. They also confirm that response messages identify the limited effect: the person was disconnected from the current voice channel, not banned. This example illustrates that accurate command language is about the scope of an action. Correct authorization and correct execution are not enough if the words promise a different outcome from the software.
Finally, the team tests the command under a moderator account with permission and an ordinary account without it. The response localization must differentiate success from lack of authority without revealing private moderation details. The test exercises the real permission path, rather than substituting a generic sample payload that cannot surface this issue. Translating administrative controls should preserve procedural meaning even when the texts contain very few words.
A release checklist that protects users and developers
The command manifest must register without validation errors in a safe environment. Localized names and descriptions should be linguistically reviewed and distinguishable in context. Choice values, option types, required flags, command scopes and permission settings must remain unchanged unless a separately approved product change requires them. The application must handle the canonical payload correctly in every tested locale and return an intelligible response using the stated user-versus-guild policy.
Add regression cases for an unsupported locale, a related fallback locale, missing optional input, a dynamic autocomplete result, an error response and a right-to-left display if supported. Review at least one desktop and one mobile client when those surfaces matter to the audience. Record the manifest hash, the test app or guild, date, client language and observed results. A check labelled “Spanish approved” without a command revision and tested interaction is too vague to reproduce later.
Classify failures by consequence. A broken handler, misleading moderation action, permission misstatement or wrong numeric value blocks release. A slightly long but understandable help sentence may be repaired in a later content pass. Document any accepted partial localization so future developers do not assume that every missing string is a new regression. This prevents both unsafe publication and perpetual rewrites over minor stylistic preferences.
The general method applies to forms, chatbots, classroom portals and games: keep the machine contract stable, translate the presentation, and test the end-to-end outcome. A payment button can say “Pay now” in several languages while retaining one action identifier. A school app can localize question labels without changing assessment response codes. A command system is a particularly clear illustration because Discord explicitly distinguishes default names, localized presentation and interaction payload fields.
Do not copy Discord-specific syntax into another platform without checking its rules. Other systems have different locale tags, length limits, fallback behavior and concepts of a default command identity. Transfer the tests, not the implementation. The durable checks are: does the target label convey the right action, does the control submit the same intended value, does the operation respect authorization and does the result appear in the right language?
Start with the most-used command in your bot. Localize one target language thoroughly and collect real user feedback about recognition, not just translation fluency. Improve the glossary and localization manifest, then expand to related commands. This is often faster than sending hundreds of short labels for translation without their functions and discovering late that ten of them are indistinguishable in the target language.
Editorial summary
Discord application-command localization is successful when users discover and invoke commands naturally in their chosen language while developers retain stable input values and reliable response logic. The key quality gates are name validity, uniqueness, fallback behavior, canonical payload identity, response-language selection and real-client testing. Do not mistake a translated picker label for a complete feature.
Build one controlled command, review each translated field against what the software actually does, inspect registered dictionaries, invoke the localized UI and verify the stable received values. Once the command passes those checks, the same matrix can be reused for more commands and locales without cloning or rewriting the underlying business operation.
Frequently asked questions
Do translated slash command names change what my bot receives?
Discord documents that interactions use default command and option names. Treat the translated names as presentation and verify that your code routes on the stable identifiers.
Why is one option localized and another not?
Application commands may be partially localized. Each relevant name or description dictionary needs its own entries and must satisfy the platform’s fallback rules.
What causes localized option-name collisions?
Two different option names may be translated into the same word. Discord requires distinct localized option names in their command context; choose disambiguating labels.
Should I translate a choice value?
Translate the displayed choice name when appropriate. Keep the stored value stable unless you are deliberately migrating the application’s data contract.
Which locale should a bot reply in?
Define a policy based on the user locale, guild locale and message surface. Private replies and public announcements may reasonably use different rules.
Why does a GET request show only one localized name?
Some command-list retrievals may return locale-specific fields instead of full dictionaries by default. Use the documented retrieval option when auditing all localizations.
Can I use spaces or punctuation in a localized slash command name?
Chat-input command names have platform naming constraints. Validate the proposed localized label against Discord’s current rules rather than assuming ordinary prose punctuation is permitted.
Does a correct command translation localize the reply automatically?
No. App-generated responses require their own localization resources and runtime locale handling.
Official references and internal links
Use Discord’s Application Commands documentation for the canonical API rules, localization dictionaries, fallbacks, option constraints and retrieval behavior. Refer to Discord’s developer documentation when reviewing integration and interaction handling. Platform behavior can change; check the docs and test client before deploying.
Continue with the How People Translate Quickly series hub . The separate guide to translating Discord chats, messages and servers serves everyday users rather than application developers, so the two articles address different tasks.
