Customizing Localized Strings in a Search Interface

When you build search pages with Coveo for Salesforce or Coveo for Microsoft Dynamics 365, you might need to localize your search pages by changing some of the strings that are displayed. With Coveo for Salesforce, you might want to add translations for strings you have written, while in Coveo for Microsoft Dynamics 365, you might want to change the attribute names displayed in a Context Facet.

Use Cases

Coveo for Salesforce

Coveo for Salesforce 2.26 (July 2016)

The Coveo JavaScript Search Framework bundled with Coveo for Salesforce comes with standard user interface string translations for several languages (see Built-in Languages).

When a user configures a personal language for their Salesforce Web user interface (see Language Settings Overview and How to change to a different language for Salesforce?) to one supported by the Coveo JavaScript Search Framework, Coveo for Salesforce search interfaces automatically open in that language. The English version of the search interface strings are always loaded and are used by default when a string is missing in the loaded localization. For unsupported languages, search interfaces also appear in English by default.

Using the Coveo Interface Editor, you can:

Coveo for Microsoft Dynamics 365

When leveraging entity context in a full search page opened from an Insight panel, some attribute labels may appear as, for instance, ADDRESS1_COUNTRY (see Leveraging Entity Context in a Full Search Page). You may want to customize these strings (see Adding a Custom Display Name for Microsoft Dynamics 365 Attributes).

Customizing Localized Strings in a Search Interface in Salesforce

  1. In Salesforce, ensure that the personal language configured for your Salesforce user interface is the language in which you want to customize the localization (see Language Settings Overview and How to change to a different language for Salesforce?).

  2. Open or reload your Coveo search interface.

    For languages supported by the Coveo JavaScript Search Framework, most search interface strings should already appear in the selected language (see Built-in Languages). Custom user interface strings and search result contents are not translated.

  3. Access the Interface Editor.

    While the Interface Editor is open, the search interface strings appear in English.

    You can open the search interface in another browser tab, without the Interface Editor, to identify the untranslated strings for which you want to customize the localization.

  4. In the Interface Editor, access the Localization panel:

    1. Click the UI Settings icon (Settings icon).

    2. Add a Localization component to your search interface, if not already done:

      In the Select a setting box, start typing Localization, and then click the Localization option.

      While you can add more than one Localization component to a search interface, you should only include one where you define all of your string translations.

  5. In the Localization panel, add one or more languages:

    1. Click Add a Language.

    2. In the Add a Language panel, in the Language key box, enter the 2 or 4-letter language code for the desired localization, referring to the Salesforce supported language list (see Which Languages Does Salesforce Support?).

      • fr for French

      • zh_CN for simplified Chinese

    3. Click OK.

    4. Repeat the previous steps to customize the localization for other languages. You can always add languages later.

    You can delete a language from the Localization panel by hovering over the language header and then clicking the Delete button that appears.

  6. Add a string localization:

    1. In the search interface, identify a string for which you want to customize the localization.

    2. In the Localization panel, click Add a String.

    3. In the Add a String panel, what you enter in the Word box depends on the string characteristics:

      • Strings hardcoded in the HTML page:

        Enter the original English exact case-sensitive string.

        To confirm that a string is hardcoded in the HTML page:

        1. At the top of the Interface Editor, click Code to access the HTML page code.

        2. Search for the string you want to translate to confirm that it is present.

        You create a custom facet labeled KB Author. In the HTML code, the facet label is defined in the data-title attribute of a CoveoFacet component, so you enter KB Author in the Word box.

        <div data-field="@kbauthor" data-title="KB Author" class="CoveoFacet"></div>
        
      • Strings coming from a CoveoJsSearch.js dictionary:

        Enter the case-sensitive JavaScript dictionary key.

        To figure out whether a string comes from a JavaScript dictionary and what its key is:

        1. In the browser tab where the Interface Editor is opened for your search interface, open the browser developer tools to inspect the code.

        2. In the Sources tabs, locate and open the CoveoJsSearch.js file (illustrated below with Chrome developer tools).

          ChromeDevTools-C4SF-CoveoJsSearchJS1

        3. In the CoveoJsSearch.js file, search for the exact string for which you want to customize the localization.

        4. Look for an occurrence in the following format:

          (function () {
            var dict = {
              ...
              "StringKey": "The string you search",
              ...
            }
          })
          
        5. Enter the corresponding StringKey in the Word box.

  7. In the Localization panel, add a translation for the added string for each language that you defined by entering the string without quotes.

    From the Localization panel:

    • You can delete a string by hovering over it, and then clicking the Delete button that appears.

    • You can’t modify a string, but you can add a new corrected one, enter the corresponding translations, and then delete the original string.

    • The order in which strings are entered doesn’t matter, as strings are only replaced when there’s an exact case-sensitive match with the key.

    Here are special cases to consider:

    • Dictionary strings containing variables {n}:

      Some original English JavaScript dictionary strings may be built dynamically by concatenating hard coded text with one or more string or numerical variables referenced with {n}, where n is 0 for the first variable, and incremented for other variables.

      When you create a translation for such a string, you should include the variable marker(s) present in the original string at the appropriate location in the appropriate order in your translated string.

      In the following original dictionary string, {0} refers to the filter name and {1} the query expression of this filter.

      "AreYouSureDeleteFilter": "Are you sure you want to delete the filter {0} with the expression {1}"
      

      For the string translated to Chinese, because of the language flow, the variable order must be inverse:

      "您是否确定要删除采用 {1} 表达式的筛选条件 {0}"
      
    • Dictionary strings containing singular and plural tags <sn></sn> <pl></pl>:

      An original English JavaScript dictionary string may contain singular/plural tags to dynamically change the string from singular to plural form, depending on the context (such as the value of a numerical variable). Anything within <sn></sn> tags only appears in a singular context, while anything within <pl></pl> tags appears in a plural context.

      When you create a translation for this type of string, if the target language also has the concept of singular/plural forms, you should include the appropriate singular and plural tags in your translation.

      In the following original dictionary string, the singular versus plural context depends on the number of available search results for the current query. Singular applies when there’s no or only one result. Plural applies when there are two or more results.

      "Results": "Result<pl>s</pl>"
      

      In French, your translation would be:

      Résultat<pl>s</pl>
      

      You can create easier to read singular and plural string forms by enclosing the whole string of each version with the appropriate tags:

      <sn>There's only one result</sn><pl>There are many results</pl>
      

      Rather than tagging each individual singular/plural difference:

      There <sn>is</sn><pl>are</pl> <sn>only one</sn><pl>many</pl> result<pl>s</pl>
      
  8. In the Interface Editor, click Save to close the Localization panel and make your changes effective.

  9. Back on the updated search interface, validate that your localization changes appear as expected.

    Repeat the previous steps to add other languages and add or modify string localization customizations.

  • The Localization panel adds a script section at the bottom of the HTML page code as shown in the following example.

    <script type="text/javascript">
        String.toLocaleString({"fr":{"Year":"Année","Month":"Mois","friday":"Vendredi"},"es":{"Year":"Año","Month":"Mes","friday":"viernes"}});
    </script>
    

    You can view and edit the localization JSON from the Code tab of the Interface Editor. This is sometimes more efficient than using the Localization panel (e.g., when you want to rename a string key).

  • To add an unsupported regional version of a base language:

    1. Set Salesforce to the base language.

    2. Copy the list of key/string pairs from the resource/[id]/coveov2__JsSearch/js/cultures/[baselang].js file.

    3. Paste the key/string pairs in the script section at the bottom of the HTML page code.

    4. Change or add the region specific strings in the Localization panel or directly in the code.

  • If you include JavaScript code in your HTML page, you can reference a localized string version as follows:

    'StringKey'.toLocaleString();
    

Adding a Custom Display Name for Microsoft Dynamics 365 Attributes

When you implement a Context Facet in a Coveo for Microsoft Dynamics 365 Insight Panel, the attribute labels in the facet may appear as, for instance, ADDRESS1_COUNTRY (see Making a Case Context Available in a Full Search Page). Follow the steps below to customize these strings.

Dynamics-ContextFacetBefore

  1. Access the Interface Editor (see Editing a Search Page).

  2. In the Interface Editor, access the Localization panel:

    1. Click the UI Settings icon (Settings icon).

    2. Add a Localization component to your search interface, if not already done:

      In the Select a setting box, type Localization, and then click the Localization option.

      While you can add more than one Localization component to a search interface, you should only include one where you define all of your string translations.

  3. In the Localization panel, add a language:

    1. Click Add a Language.

    2. In the Add a Language panel, in the Language key box, enter the 2 or 4-letter language code for the desired localization.

      Typically, to add a custom display name for attribute labels, you could enter en for English.

      However, to replace the English labels with French or simplified Chinese ones, you could enter fr or zh_CN respectively.

    3. Click OK.

    You can delete a language from the Localization panel by hovering over the language header and then clicking the Delete button that appears.

  4. Add a string localization for the attribute label you want to replace with a custom display name:

    1. In the search interface, identify a string for which you want to customize the localization.

    2. In the Localization panel, click Add a String.

    3. In the Add a String panel, in the Word box, enter the string to replace. This box is case-sensitive, so make sure to enter your string the same way it appears in the page code.

      To confirm how a string is hardcoded in the HTML page:

      1. At the top of the Interface Editor, click Code to access the HTML page code.

      2. Search for the string you want to translate.

      You created a Context Facet with attributes accountnumber and address1_country. In the HTML code, the facet attributes labels are defined in the data-attributes attribute of a CoveoContextFacet component, so you enter accountnumber, and then address1_country in the Word box.

      <div class="CoveoContextFacet" data-logical-name="account" data-identifier-attribute="accountid" data-attributes="name, revenue, accountnumber, address1_country"></div>
      
  5. Back in the Localization panel, add the desired display name for the each attribute label. No quotation marks are required.

    From the Localization panel:

    • You can delete a string by hovering over it, and then clicking the Delete button that appears.

    • You can’t modify a string, but you can add a new corrected one, enter the corresponding string to display, and then delete the original string.

    • The order in which strings are entered doesn’t matter, as strings are only replaced when there’s an exact case-sensitive match with the key.

  6. Click Apply to close the Localization panel and make your changes effective.

  7. When you’re done editing your search page, in the top right corner of the Interface Editor, click Save.

  8. Publish your changes (see Publishing a Search Page).

  9. Reload your search interface, and then validate that your localization changes appear as expected.

    Dynamics-ContextFacetAfter

The Localization panel adds a script section at the bottom of the HTML page code as shown below.

<script type="text/javascript">String.toLocaleString({"en":{"address1_country":"COUNTRY","accountnumber":"ACCOUNT NUMBER"}});</script>

In the Interface Editor Code tab, you can view and edit the localization JSON when this is more efficient than using the Localization panel, such as for renaming a string key.

Recommended Articles