Customizing application labels

The beqomPay Suite 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.

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 Labelingis available under Workbench > Data Management > Custom Labeling. Access to Workbench depends on your role within the platform.

Users with Configuration and LocalizationAdmin professional roles have access to the feature.

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 (such as 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 selectView 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: 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 contains a second tab called Audit trails, in which you can check upload information after you have uploaded customized files. For more information, see Using the audit trail.

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 dots icon located in 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.

File 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.

This is an attention message.

While .csv files can be opened using worksheet applications such as Microsoft Excel or Apple Numbers, beqom recommends that you open those files and work in them using a text editor, such as Notepad++. This is due to the fact that these applications can have trouble handling and rendering special language-specific characters, such as Japanese characters or German accented letters.

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 give 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, as recommended, 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.

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 localization 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 don't 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 perform 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 next 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 Pay Suite. beqom however 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 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, 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 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 don't 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 4th 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.

Best practices & limitations

Best practices

To make sure that the feature behaves as expected, please follow the following 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 between 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's 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.
Limit your tests to the labels you actually want to change, due to the label deletion limitation.

Known limitations

It is currently not possible to delete a custom label. For the system to return to the standard values, you can still use of the following methods:

Insert the standard value from column B into column C. This way the system will use the standard value as the custom value.
Set column D to FALSE. This way, the system will ignore the custom value entirely and use the the standard value.