All Products
Search
Document Center

Captcha:Customize text and language settings

Last Updated:Mar 03, 2026

Captcha 2.0 supports 17 built-in languages and lets you customize the text displayed in each CAPTCHA component. Set the language parameter for basic localization, or define a myLang object to override specific text strings.

Supported languages

Set the language parameter in initAliyunCaptcha to one of the following codes:

CodeLanguage
cnSimplified Chinese
twTraditional Chinese
enEnglish
arArabic
deGerman
esSpanish
frFrench
inIndonesian
itItalian
jaJapanese
koKorean
msMalaysia
ptPortuguese
ruRussian
thThai
trTurkish
viVietnamese
Important

Captcha 2.0 uses custom language codes that differ from ISO 639-1 for certain languages. For example, Simplified Chinese uses cn (not zh), Traditional Chinese uses tw (not zh-TW), and Indonesian uses in (not id).

If the specified language code is not in the list above, Captcha 2.0 returns the default Chinese text.

Spatial reasoning CAPTCHA language support

Spatial reasoning CAPTCHAs support five languages: cn, tw, en, ja, and ko. All other language codes fall back to Chinese for spatial reasoning CAPTCHAs.

Note

The spatial reasoning CAPTCHA type will be unpublished soon. For more information, see Notice of spatial reasoning CAPTCHA type unpublishing.

Set the language

Pass the language parameter to initAliyunCaptcha:

initAliyunCaptcha({
  // ... other parameters
  language: "en",
  // ... other parameters
});

This applies the built-in text for the specified language to all CAPTCHA components.

Customize text strings

Captcha 2.0 provides 13 text keys that control all user-facing strings in the CAPTCHA UI. Define a myLang object with custom values for any of these keys, then pass it through the upLang parameter.

Override built-in text

/**
 * Define custom text for one or more languages.
 * Each language key contains the same set of text keys.
 */
var myLang = {
  cn: {
    START_VERIFY: "Click to start verification",
    POPUP_TITLE: "Complete Security Verification",
    SLIDE_TIP: "Drag the slider all the way to the right",
    CHECK_BOX_TIP: "Confirm you are not a robot",
    PUZZLE_TIP: "Drag the slider to complete the puzzle",
    INPAINTING_TIP: "Drag the slider to restore the complete image",
    VERIFYING: "Verifying...",
    SUCCESS: "Verification successful!",
    SLIDE_FAIL: "Verification failed, please refresh and try again",
    CAPTCHA_FAIL: "Verification failed, please try again!",
    CONGESTION: "Traffic congestion, please refresh and try again",
    CAPTCHA_COMPLETED: "Sliding completed",
    FINISH_CAPTCHA: "Please complete verification first!",
  },
  en: {
    POPUP_TITLE: "Please complete captcha",
    // ... add other keys as needed
  },
};

initAliyunCaptcha({
  // ... other parameters
  upLang: myLang,
  language: "cn",
  // ... other parameters
});

Only include the text keys you want to override. Keys not specified in myLang use the built-in default for the selected language.

Add an unsupported language

To use a language not in the built-in list, set the language parameter of initAliyunCaptcha to the required language, prepare custom text in that language, and then specify the custom text as the values of the text keys in the myLang object. It is recommended to provide all 13 text keys. Any keys not provided fall back to the default Chinese text.

var myLang = {
  xx: {
    POPUP_TITLE: "Custom text in the xx language",
    START_VERIFY: "...",
    // ... define other keys
  },
};

initAliyunCaptcha({
  // ... other parameters
  upLang: myLang,
  language: "xx",
  // ... other parameters
});
Important

If the custom language code has no corresponding entries in myLang, the system returns the default Chinese text.

Text keys reference

The following table lists all 13 customizable text keys, their default values, and which verification types they apply to.

Interaction prompts

KeyDefault valueApplies toDescription
START_VERIFY"Click to start verification"Puzzle, Image restorationEmbedded trigger button text in V3 architecture
POPUP_TITLE"Please complete security verification"All typesTitle displayed at the top of the CAPTCHA prompt
SLIDE_TIP"Drag the slider all the way to the right"SliderInstruction text for slider verification
CHECK_BOX_TIP"Confirm you are not a robot"One-clickInstruction text for one-click verification
PUZZLE_TIP"Drag the slider to complete the puzzle"PuzzleInstruction text for puzzle verification
INPAINTING_TIP"Drag the slider to restore the complete image"Image restorationInstruction text for image restoration

Status messages

KeyDefault valueApplies toDescription
VERIFYING"Verifying..."Slider, One-clickDisplayed while the verification request is processing
SUCCESS"Verification successful"All typesDisplayed after successful verification
SLIDE_FAIL"Verification failed, please refresh and try again"Slider, One-clickDisplayed when slider or one-click verification fails
CAPTCHA_FAIL"Verification failed, please try again!"Puzzle, Image restorationDisplayed when puzzle or image restoration verification fails
CONGESTION"Traffic congestion, please refresh and try again"All typesDisplayed during network issues

V2 architecture messages

KeyDefault valueApplies toDescription
CAPTCHA_COMPLETED"Sliding completed"Slider, Puzzle, Image restorationDisplayed after the user completes the interaction, before submitting verification. Specific to V2 architecture-embedded, triggered by business buttons.
FINISH_CAPTCHA"Please complete verification first!"All typesDisplayed when the user attempts to submit without completing the CAPTCHA. Specific to V2 architecture-embedded, triggered by business buttons.
Note

CAPTCHA_COMPLETED and FINISH_CAPTCHA are specific to V2 architecture-embedded mode. The V2 embedded interaction experience is suboptimal. Integrate the V3 architecture-embedded interaction UI instead. To submit verification immediately after sliding in V2 mode, set the immediate parameter to true during initialization. Changing the prompt position of FINISH_CAPTCHA is not supported.

Non-customizable text

The following system messages cannot be overridden:

  • "Verification timeout, please close the CAPTCHA and try again"

  • "Verification timeout, please click on the CAPTCHA frame and try again"

  • "You stay on the page for a long period of time. Refresh and try again later."

Text positions in the CAPTCHA UI

The following table shows where each text key appears across the four verification types. A "/" indicates the key does not apply to that type.

KeySlider verificationOne-click verificationPuzzle verificationImage restoration
START_VERIFY//imageimage
POPUP_TITLEimageimageimageimage
SLIDE_TIP / CHECK_BOX_TIP / PUZZLE_TIP / INPAINTING_TIPimageimageimageimage
VERIFYINGimageimage//
SUCCESSimageimageimageimage
SLIDE_FAILimageimage//
CAPTCHA_FAIL//imageimage
CONGESTIONimageimageimageimage
CAPTCHA_COMPLETEDimage/imageimage
FINISH_CAPTCHAimageimageimageimage
Timeout messages (not customizable)image imageimage imageimage imageimage image