Customizing application labels

The beqomPaySuite application offers you the possibility to customize the labels (i.e., button text, messages, navigation element names, etc.) displayed in the application interface. This allows you to tailor the application to your own branding and corporate terminology, making sure that all users get as seamless an experience as possible.

The PaySuite application is available in English (United States), English (United Kingdom), French, German, Italian, Thai, Spanish, Portuguese, Dutch, Indonesian, Japanese and Turkish. The default language is English (United States).

Using the Custom Labeling feature, you can input your own values for all the labels available in the application, for all the languages supported in the platform. Using the feature, you can export language-specific CSV files, update custom translation values locally, and upload them back into the platform. In this way, the feature provides a safe and predictable workflow for personalizing your translations. Conveniently, it also supports bulk updates across multiple languages in a single upload action.

This is a tip message.

Custom Labeling is available under Workbench > Data Management > Localization > Custom Labeling. Access to Workbench depends on your role within the platform.

The feature is available to the Configuration and the LocalizationAdmin professional roles.

The Custom Labeling page consists of several key elements:

The Total languages and Custom overwrites tiles, which display the number of languages available in the application and the number of languages with customized labels.
A list of languages that contains information such as language names with local variants in brackets (for instance, English (United States) or Portuguese (Portugal)), language codes, and the translation sources (custom or standard).
A toolbar which enables you to perform actions such as downloading templates or uploading files.

The page also includes a search bar at the top of the language table and pagination at its bottom for fast and easy navigation.

The following figure illustrates the Custom Labeling page:

Custom Labeling section in Workbench > Data Management

Viewing the details of a language

Within the Custom Labeling page, you can view details related to each of the languages available in the application. When you click any of the languages listed in the table on the Custom Labeling page, the Language details drawer opens on the right. The drawer will also appear if you click the three-dot icon at the far right of each row in the language list, and then select View in the action menu.

The Language details drawer offers, in the Details tab, information such as:

Name of the language. For example, English (United States).
Language code. For example, en-US.
The translation source: a flag that indicates whether or not customizations have been performed on the language.
Last update date (relevant only if customizations have been performed).
User who performed the last update.

The following figure illustrates the Details of the Language details drawer:

Language-specific information

This is a tip message.

The Language details drawer also contains two additional tabs: Versions, where you can view the version history of a language's custom labels and restore a previous version, and Audit trails, in which you can check upload information after you have uploaded customized files. For more information, see Viewing the version history & restoring a previous version and Using the audit trail below.

Downloading CSV templates

When you first start using the custom labeling feature, your environment will be free of all customizations. To start using the feature and customizing the platform, you first need to download the localization file templates that contain the technical key and the standard value for each technical key.

The platform offers four different download options:

You can click Download all in the page toolbar. This will download an individual file for each of the available languages. You can also check the box corresponding to the language(s) for which you want to download the file; then the Download all button switches to Download. You can then click it to download the file for each of the selected languages.

You can click the Upload file button located next to the Download/Download all button. Upon doing so, the File upload window is displayed. You can then click Download the template, which opens a drop-down list where you can either click Download all to download all files or choose a specific file.

Language template selection
You can also download the CSV file for a particular language by clicking the three-dot icon located at the far right of each language row in the language list. You can then simply click Download CSV in the action menu.
Finally, you can click a language name in the table; a drawer with language details is then opened on the right side of the application screen. There, you can simply click the Download CSV file button located in the lower-right corner of the drawer.

This is an note/information message.

Please note that once customizations have been made to the files, then those customizations will be included in the downloaded files.

Files downloaded using either of the methods above are saved locally on your computer with names that follow the values displayed in the Code column of the language list. For instance, the file for US English is downloaded as en-US.csv, the file for German is downloaded as de-DE.csv, etc.

Understanding the structure of the CSV files

Files in .csv format have a specific structure that needs to be understood before starting to make changes.

If you open the files with Excel or Numbers, you will see four columns:

Key: technical keys (i.e., unique identifiers) of the platform labels.
Standard_value: default application labels (i.e., labels provided for the application interface by beqom).
Custom_value: personalized value for each technical key (if any).
Is_custom_value: Boolean flag (TRUE/FALSE) that indicates whether the system should take into account a given value. By default, this column is empty, but considered TRUE. This means that when a custom value is entered in Custom_value and this field is left blank, then the value will be used by the system. Setting it to FALSE will indicate to the system that it can ignore the custom value entirely.

If you open the files using a text editor, you will see the structure below (in this example, the file is opened in Visual Studio Code):

CSV file in a text editor

You can see that a similar structure as the one described above is available. In row 1, we find again the key, standard_value and custom_value indicators.

In this format, custom values can be entered after the standard value in each individual row.

This is a tip message.

If you are going to be working with labels in a text editor, please refer to the Best practices & limitations section.

Entering a custom value for a key

After you download the CSV files on your device, you can start editing them. Before you start entering custom values, you must get familiar with the following operating principles:

The length of each custom value is limited to 1000 characters (spaces included).
Any changes you make to the technical key or the standard value will be entirely ignored by the system.

To start entering custom values, proceed as follows

Open a relevant file locally.
Find the key that corresponds to the label you want to change. Since the same text can be found in many places, you need to make sure that you target the right one. To make sure that this is the case, beqom recommends that you disable the application localization to show the technical keys in the interface, as described in Adjusting cultural settings.
Type the desired value in the custom_value column to personalize your translations. If you have opened the file in a text editor, the custom value should be entered after the standard value as follows:

Copy

admin_appearance_theme_title,Theme,Color

When you are done making changes, save the file on your device, in a location where you can easily find it.

Uploading customized files

Once you have made changes to one or several files on your local computer, you can upload the edited file(s) for the application to take the changes into account. To do so, proceed as follows:

Click the Upload file button in the far right of the Custom Labeling page toolbar, located above the list of languages. The File upload contextual window opens.
Click Upload to choose one or several files from your local device. Alternatively, you can drag and drop your files in the dropbox. You can select/drop multiple files simultaneously.
Click Start upload to begin uploading your files.
You can also upload additional files at a later time by clicking Upload additional files in the Upload finished pop-up window that will appear.

This is an note/information message.

The application supports only the .csv format. 10 MB is the maximum size for a file. Files that do not respect these requirements will be rejected by the system. Additionally, files that have been renamed will also be rejected.

During the uploading process, the system performs a number of validation steps on the files. If the validation is successful, a green confirmation icon is then displayed next to the name of successfully uploaded files in the Upload finished window, as illustrated in the following figure:

Successful file upload validation

If errors are detected during upload, a red failure icon is displayed next to the name of the relevant file in the Upload finished window, as illustrated in the following figure:

Validation error message

Validation will fail if any of the following events occur:

Incorrect file format: the application only supports .csv format
Multiple files uploaded for a single language
Renamed file; the file names must match those of the downloaded files as well as the language code available in the application
The CSV file does not contain the key, standard_value, or custom_value columns
The order of the columns does not match the original structure
Column headers have been modified

However, the system will ignore the following changes:

The technical key has been removed or changed
The standard value has been removed or changed

The changes included in successfully processed files are immediately applied in PaySuite. However, beqom recommends that you perform a hard-refresh of the page in your Web browser to make sure you see all required changes.

Using the audit trail

The Audit trails tab, available in the Language details drawer, documents the upload history of a specific language. It contains information such as:

The date and time of the import
The name of the user who performed the import
The number of labels that were created
The number of labels that were skipped
The number of labels that were reverted to standard

The following figure illustrates the Audit trails tab:

List of uploads performed for a single language in the audit trail

In addition to the information listed above, the Audit trails tab also enables you to view additional information about each upload, by clicking Show details in the box corresponding to each upload. Upon doing so, a JSON information file is displayed with additional information, including invalid keys, as illustrated in the following figure:

Import metadata

This is an note/information message.

The system counts labels created and labels skipped as follows:

The first time a custom value is entered and uploaded, the system takes it into account and counts it as "label created."
Upon subsequent uploads, custom values that already existed in the file and remained unchanged are counted as "label skipped."
If an already existing custom value is edited, then it is counted as "label created" at the next upload.

Editing a custom label

Existing customizations performed to a given language can be modified or removed.

To edit a custom label, proceed as follows:

Download the file corresponding to the language in which you want to work using one of the methods described in Downloading CSV templates.
Open the file locally using the program of your choice and then locate the custom value that you want to change/remove.
Change the value to the new value. If you want to revert the custom label to its standard value, paste the standard value in place of the custom value.
Save the file locally.
Upload the file into the system as described in Uploading customized files.
Refresh your Web browser page. The new custom value is applied (or the standard value is applied again).

Marking a custom label as unused

You can mark a custom label as unused if you have previously customized it and do not want to use the custom value anymore.

To do so, proceed as follows:

Retrieve the custom localization file in which the label is located and open it.
Locate the label in the file.
Set the value of the fourth column (is_custom_value) for the key to FALSE.
Save your changes.
Reimport the file into the platform using the method described in Uploading customized files.

Resetting custom labels

The above methods change or remove custom labels one at a time. Instead of manually editing and re-uploading a CSV file, you can also reset one or more languages back to their standard values in a single action.

This is an note/information message.

Resetting custom labels is available only to users with the Configuration or Support role.

You can trigger a reset in any of the following ways:

From the language list, check the box next to one or more customized languages. Then, click Reset above the list. This button only appears when at least one selected language has custom labels.
Click the three-dot icon at the far right of a customized language's row. Next, select Reset to standard in the action menu.
Open the Language details drawer for a customized language and click Reset to standard at the bottom of the drawer.

The following figure presents a customized language ready to be reset:

Selecting a language for reset in Custom Labeling

In every case, a confirmation window appears, warning you that the action will delete all custom labels and version history for the affected language(s) and revert them to standard system values. Click Reset to default to confirm or Cancel to close the window without resetting anything.

Once the reset completes, a confirmation message is displayed.

Viewing the version history & restoring a previous version

The Versions tab of the Language details drawer lists every recorded version of a language's custom labels, from the most recent to the oldest, with the current version marked.

This is an note/information message.

Viewing this tab requires the Configuration or Support role, in addition to the base access needed to upload and download CSV files described above.

Each version entry shows:

A version number, counting down from the most recent change.
A tag indicating what created the version: CSV upload, Restore, or Cleanup (i.e., a reset).
A Current version tag on the most recent entry.
The date and time of the change, as well as the name of the user who made it.
The version number it was restored from or the number of labels updated in that version.

The following figure illustrates the Versions tab:

Version history for a custom label

If no customizations have been made to a language yet, you will see an empty state in the tab instead of a version list.

Downloading the CSV file for a specific version

To download the CSV file exactly as it existed at a given version, click Download next to that version. The file downloads immediately, using the same file name as the language's regular CSV download.

Restoring a previous version

To restore a language to an earlier version, proceed as follows:

Click Restore next to the version. This button is not shown next to the current version. A confirmation window appears, warning you that this will overwrite your current labels with the selected version and replace any changes made after it.
Click Restore version to confirm or Cancel to close the window without restoring anything. Once the restore is complete, a confirmation message is displayed, and the restored version becomes the new current version.

Best practices

To make sure that the feature behaves as expected, please follow these recommendations:

For languages that contain special characters (i.e., accented characters such as é, ü, ô, ñ or non-Latin alphabets such as Japanese or Thai), beqom recommends that you open the files in a text editor such as Notepad++. To be able to use Excel, make sure you use UTF-8 encoding when opening the files.
When working in a text editor, make sure that you respect the following rules:
- When a file is opened in Notepad++, labels that contain commas ( , ) should always be wrapped in double quotes ( " ). Spreadsheet tools such as Excel handle this natively, but when editing in a text editor, this needs to be done. Essentially, this is due to the very nature of CSV files: comma-separated values, i.e., each comma creates a new value.
- Similarly, any label that contains double quotes ( " ) should always be included in double quotes, and the double quotes should be escaped with other double quotes. Essentially, there should be 6 double quotes in these types of labels, like in this example: "He said ""hello"""
- \n can be used in custom values to create a new line, but these labels must also be wrapped in double quotes. Example: "Line 1\nLine 2"
- Leading and trailing spaces are technically possible, but many parsers strip them. It is therefore possible that the system will ignore them.
- Characters such as &, <, >, #, @, %, !, *, /, \ are not special characters in CSV, so no special handling is required for them.
- Unicode and accented characters (é, ü, ñ…) are safe as long as the file is saved in UTF-8. This is the main reason why these files need to be opened in Notepad++ rather than Excel.