--- title: Enabling and customizing language localization for SMS authentication in PingID description: If SMS is selected as an alternate authentication method, enable localization and customization of the SMS message a user receives. component: pingid page_id: pingid:pingid_service_management:pid_enabling_customizing_localization_sms_authentication canonical_url: http://docs.pingidentity.com/pingid/pingid_service_management/pid_enabling_customizing_localization_sms_authentication.html revdate: March 31, 2023 section_ids: enabling-language-localization-for-sms-authentication: Enabling language localization for SMS authentication about-this-task: About this task steps: Steps result: Result: managing-online-customization-of-the-sms-authentication-message: Managing online customization of the SMS authentication message steps-2: Steps result-2: Result: next-steps: Next steps managing-offline-customization-of-the-sms-authentication-message: Managing offline customization of the SMS authentication message about-this-task-2: About this task steps-3: Steps result-3: Result: result-4: Result: choose-from: Choose from: result-5: Result: result-6: Result: offline-customization-additional-actions: "Offline customization: additional actions" restoring-a-previously-removed-language: Restoring a previously removed language reverting-to-default-languages-and-sms-texts: Reverting to default languages and SMS texts --- # Enabling and customizing language localization for SMS authentication in PingID If SMS is selected as an alternate authentication method, enable localization and customization of the SMS message a user receives. Language localization applies to both registration and authentication. The language is defined by the language settings of the web browser on the device from which the user initiated the authentication or registration request. For a list of supported languages, see [PingOne for Enterprise language support](http://docs.pingidentity.com/pingoneforenterprise/pingone_for_enterprise/p14e_language_support.html). | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | * If the user's browser is set to a language that is not supported, the default language of English is used. * All account types support localization. Customization is supported for full accounts only. * SMS messages longer than 67 characters might incur additional charges. The SMS service provider might split longer messages into several shorter messages, each billed on its own. | When localizing or customizing the SMS messages: * You can enable localization only using predefined messages for all supported languages. For more information, see [Enabling language localization for SMS authentication](pid_enabling_language_localization_sms_authentication.html). * You can use the basic online SMS message editor. For more information, see [Managing online customization of the SMS authentication message](pid_managing_online_customization_sms_authentication_message.html). * You can use offline editing for multiple-language SMS messages with language inclusion and exclusion. For more information, see [Managing offline customization of the SMS authentication message](pid_managing_offline_customization_of_sms_authentication_message.html). ## Enabling language localization for SMS authentication Enable localization to ensure that SMS messages on a user's device will appear in the language set for the device browser. ### About this task If the language used in the browser is not one of the supported languages, the default language of English is used. ### Steps 1. Sign on to the admin console. 2. In the PingID admin portal, go to **Setup → PingID → Configuration**. 3. In the **Authentication** section, go to **Alternate Authentication Methods**. ![A screen capture of the Alternate Authentication Methods window. Each available method has an Enable check box option. All options have this check box selected. SMS, voice, and email also have check boxes for Pre-populate, Restrict, and Backup Authentication. SMS, voice, and email all have the Backup Authentication check box selected.](_images/vkb1564020562147.png) 4. In the **Enable** column, ensure that **SMS** is selected. #### Result: The **Local Language For SMS** section is displayed. ![A screen capture of the Local Language For SMS section. The Disable option is selected.](_images/lfr1572436666586.png) 5. To enable language localization, click **Enable**. 6. Click **Save**. ## Managing online customization of the SMS authentication message You can customize the SMS authentication message in the PingID admin portal. ### Steps 1. Follow steps 1-5 of [Enabling language localization for SMS authentication](pid_enabling_language_localization_sms_authentication.html). #### Result: The **Local Language For SMS** section expands. ![A screen capture of the Local Language For SMS section. The Enable option is selected. The SMS message content field shows sample text "Your Ping ID authentication is ${OTP}." Next to the Content label is the hyperlink option for Reset.](_images/xwp1572439666458.png) 2. In the **Content** field, configure the SMS authentication message, or accept the default. ![A screen capture of the Content field. The SMS message content field shows sample text "Your Ping ID authentication is ${OTP}." Next to the Content label is the hyperlink option for Reset.](_images/ioy1572442838629.png) | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The editor will display an error message if the one-time passcode (OTP) system variable is missing. The variable must be surrounded curly braces and can be upper or lower case, such as `${OTP}`.To revert back to the default message, click **Reset**.![A screen capture of the Content field displaying an error because the OTP variable is missing.](_images/pvw1572440588650.png) | 3. Click **Save**. ### Next steps To customize additional languages, click the **Language** icon, and then select a language from the list. ![A screen capture of the language list. The default is English, shown with a small dot next to it.](_images/nib1572448488887.png) Edit the SMS message as described previously, and then click **Save**. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | If your locale does not allow you to type in the language of choice, you must use the offline method described in [Managing offline customization of the SMS authentication message](pid_managing_offline_customization_of_sms_authentication_message.html). | ## Managing offline customization of the SMS authentication message Offline customization provides a central place to manage all of your PingID localizations and allows for the inclusion and exclusion of languages. ### About this task To edit language messages outside of your selected language, download the message `.zip` file, extract the message files, edit them, rebuild the .zip file, and upload it to the PingID admin portal. ### Steps 1. Follow steps 1-5 of [Enabling language localization for SMS authentication](pid_enabling_language_localization_sms_authentication.html). #### Result: The **Local Language For SMS** section expands. ![A screen capture of the Local Language For SMS section. The Enable option is selected. The SMS message content field shows sample text "Your Ping ID authentication is ${OTP}." Next to the Content label is the hyperlink option for Reset.](_images/xwp1572439666458.png) 2. Click the **Language** icon, and then select a language from the list. ![A screen capture of the language list. The default is English, shown with a small dot next to it.](_images/nib1572448488887.png) 3. To start the offline customization procedure, click **Edit Localization File**. #### Result: The **Localization** window opens. ![A screen capture of the Localization window. There is a button to Download Ping Defaults for messages that you might need to localize. In the Upload Localization File section, there are buttons to Choose File and Download Current File for language localization.](_images/urf1572503033389.png) 4. For first-time customization, click **Download Ping Defaults**. If you are continuing from an earlier customization, click **Download Current File**. #### Choose from: * **Download Ping Defaults**: You receive a file called `LocalizationsTemplate.zip`. * **Download Current File**: You receive a file called `Localizations.zip`. The `LocalizationsTemplate.zip` file contain a properties text file for each supported language. ![A screen capture of the file list.](_images/zjf1572507740308.png) Each of the properties files is a text file with the same layout. ``` pingid.sms.msg.authentication=Your Ping ID authentication code is: ${OTP} pingid.enrollment.content.description=Great news! Your company is giving you the simplicity of PingID, so you can sign on to all your applications with the added security of a swipe on your mobile device. Enter your email address, and we'll send you a link to download PingID. pingid.non.app.enrollment.text=I want to use a different authentication method. ``` 5. Extract the `.zip` file. As a concrete example, we will edit the English file and remove several languages. 1. Open `Localization_en.properties` in a text editor. 2. Locate the line commencing with `pingid.sms.msg.authentication=`. 3. Change the line to your desired message, such as `pingid.sms.msg.authentication=Here is your Ping ID authentication code: ${OTP}`. There are several rules for editing language properties files and creation of the `.zip` file: * The OTP variable is in curly braces \\{..} * Do not edit the other lines because they are used in other parts of the system. * You can revert the SMS authentication message to the default for the language by setting `pingid.sms.msg.authentication=` (without a value) or simply deleting the line. * The `.zip` file must be a flat structure containing only the desired language files, without any folder structures. Attempts to upload invalid `.zip` structures returns the error message: `File doesn't contain any valid localizations`. * Only files with filenames complying with the `Localization_.properties` naming convention are uploaded. * Files whose filenames do not comply with the `Localization_.properties` naming convention are ignored. This permits inclusion of instruction and maintenance files in the `.zip`, for example `readme.txt`. * Localization files for unsupported locales are ignored. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The localization properties files are shared across several customizations, currently SMS and Enrollment co-branding. For more information, see [Customizing the PingID enrollment page (legacy)](pid_customizing_enrollment_page_legacy.html). | 4. Save the file. 5. To remove several languages, in the directory of properties files, delete all of the files except the following: ![A screen capture of the .properties files that must be retained according to your needs.](_images/xcp1572509522472.png) 6. Pack the remaining properties into a new `.zip` file, and give it a new name, such as `Localizations_.zip` The name is unimportant because it is not preserved in the system. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The `.zip` file must be a flat structure containing only localization properties files and without any folder structures.- Attempts to upload invalid zip structures returns the error message: `File doesn't contain any valid localizations`. - Only files with filenames complying with the `Localization_.properties` naming convention are uploaded. - Files whose filenames do not comply with the `Localization_.properties` naming convention are ignored. This permits inclusion of instruction and maintenance files in the `.zip`, for example `readme.txt`. - Localization files for unsupported locales are ignored. | 6. Upload your new `Localizations_.zip` file. 7. In the PingID admin portal, go to the **Localization** window, and then click **Choose File**. 8. Select `Localizations_.zip`. #### Result: You are shown confirmation. ![A screen capture of the Localization window, showing the languages updated and removed in the imported file.](_images/hmu1572514157022.png) 9. Click **Save**. #### Result: You are asked for final confirmation. ![A screen capture of the final confirmation message. The message starts with Important in all caps and the phrase to confirm "Removing the following languages will reset them to Ping defaults." After the message is the Confirm button and the hyperlink to Cancel.](_images/vwx1572514442818.png) 10. To complete the procedure, click **Confirm**. * If there are no language removals, you must click **Save** to complete the upload. * You can return to edit your localizations. In step 2, click **Download Current File**. The downloaded file is always called `Localizations.zip`. Then proceed from step 3. 11. Go to **Setup → PingID → Configuration** and confirm your edit by checking your SMS message settings. ### Offline customization: additional actions For additional tasks for offline customization of the SMS authentication message, see the following sections. #### Restoring a previously removed language 1. In the admin portal, go to the **Localizations** window. 2. Click **Download Current File** and extract it. 3. If you do not have the default `.zip` file, click **Download Ping Defaults**. 4. Copy the relevant language properties file from the template to your extracted files directory. 5. Edit the language properties files as required. 6. Rebuild the `.zip` properties file. 7. Upload the zipped file. #### Reverting to default languages and SMS texts | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The following steps use the example in [Managing offline customization of the SMS authentication message](pid_managing_offline_customization_of_sms_authentication_message.html). | 1. In the admin portal, go to the **Localizations** window. 2. Under **Choose File**, click **Remove**. The proposed action is summarized. ![A screen capture of the Localization window, showing the languages in the current file that will be removed. The languages updated and languages removed are surrounded by a red rectangle..](_images/paw1572530361041.png) 3. Click **Save**. A confirmation window opens. ![A screen capture of the confirmation window. The message starts with Important in all caps and the phrase to confirm "Removing your localization file will reset your languages to Ping defaults." After the message is the Confirm button and the hyperlink to Cancel.](_images/icc1572525151906.png) 4. Click **Confirm**. All languages become available with their default SMS messages.