Skip to main content
Version: 9.5

Internationalization, Step By Step

Qrvey supports a process for displaying text in any number of languages.

Text Types​

There are two types of text:

  • Static Text is built into the Qrvey product pages. These are titles, labels, tooltips, buttons, menus, and such.
  • Dynamic Text is the text that is entered by Qrvey Composer users. This is text such as Dataset names and Dataset column names.

Translated values are entered and stored in a Google spreadsheet. The spreadsheet contains a key for each text segment. The translation process involves entering values for each language for each key. The spreadsheet can be shared with any number of people involved in the translation process. A utility adds new keys to the spreadsheet, and then later “publishes” translated text back to Qrvey.

The following platforms and tools are used in the process:

  • Translation Spreadsheet - This Google spreadsheet is used to facilitate the translation process by housing the keys and translations for all static and dynamic phrases.

  • Qrvey Translation Service Utility - This utility imports “keys” into the Translation Spreadsheet, and then exports translated values back into Qrvey. This spreadsheet is accessed through an API that requires a Google Cloud Platform account.

  • Google Cloud Platform account - This free GCP account is used to facilitate access to the Translation Spreadsheet.

The full process can be broken down into the following high-level steps that each might be best performed by a specific persona.

Note: The internationalization process requires a Google Cloud Platform account (see https://cloud.google.com/ to create your free account).

Step 1: Set Up a Google Spreadsheet API​

  • Recommended Persona: Cloud Ops engineer
  • Prerequisites: A GCP account and credentials to access and create projects in it

Create a new project in your GCP account and enable the Google Spreadsheet API used by Qrvey to access the Translation Spreadsheet. Google does not charge for creating an account or spreadsheet API access.

  1. Create a Google Cloud Platform account by visiting https://cloud.google.com/ or log into your existing GCP account.

  2. From the Google Cloud dashboard, create a new project. This option can also be found by typing “Create a Project” in GCP’s search bar.

  3. Enable the Google Spreadsheet API.

    a. Create a credential email address.

    • Below “APIs & Services”, select “Library”. This option can also be found by typing “Sheets API” in GCP’s search bar.
    • Select “Google Sheets API”.
    • Select “Enable”.
    • Select the “CREDENTIALS” tab.
    • Select “+ CREATE CREDENTIALS”.
    • Select “Service Account”.
    • Enter a “Service account name”, for example, “Qrvey Translation”.
    • Select “CREATE AND CONTINUE”.
    • Skip the section for “account access”.
    • Select “Done”.
    • Save the generated email address listed under “Service Accounts”, ending in iam.gserviceaccount.com.

    b. Create the private key.

    • Select the new Service Account’s email address.
    • Select “KEYS”.
    • Select “ADD KEY”.
    • Select “Create new key”.
    • Select “JSON”, then select "CREATE".
    • A JSON file is downloaded by the browser. Open the JSON file.
    • Save the value of private_key, the part that is within double quotes.

Step 2: Create a Translation Spreadsheet and Configure the Environment​

  • Recommended Persona: Cloud Ops engineer
  • Prerequisites: Access to the environment configuration file used to create or update the Qrvey environment, and the service account email and private key generated in the previous step

Create a blank translation spreadsheet and provide its Google Spreadsheet API credentials to the Qrvey environment so it can be accessed by the Translation Service Utility.

  1. Create the translation spreadsheet.

    • Open the sample translation spreadsheet.

    • From the File menu, select Make a copy. This copy will be used to enter translated text for your deployment.

    • Rename this spreadsheet as needed.

    • From the spreadsheet’s URL, save the document ID. For example:

      URL: https://docs.google.com/spreadsheets/d/1YygAI9_UoRefEjDfUYAKh62FMZWJMjKJHDFZ6wzws/edit#gid=0
      DOC ID: 1YygAI9_UoRefEjDfUYAKh62FMZWJMjKJHDFZ6wzws

    • Share this spreadsheet as “Editor” with user accounts of people who will enter or review translations.

    • Share this spreadsheet as “Editor” with the email account saved above (ending in iam.gserviceaccount.com).

  2. Configure the Translation Service Utility.

    Qrvey environments are now multi-platform deployments. The Translation Service Utility is configured by adding a globalization block to the environment configuration file (config) that is submitted when the environment is created or upgraded.

    The globalization object goes inside the variables object of the config.json file, at the same level as the other environment variables (for example, after initial_admin_email and staging_instance). Replace the placeholder values with your own:

    {
      "account_config": {},
      "variables": {
        "registry_user": "<REGISTRY_USER>",
        "registry_key": "<REGISTRY_KEY>",
        "qrvey_chart_version": "<QRVEY_VERSION>",
        "initial_admin_email": "<ADMIN_EMAIL>",
        "staging_instance": true,
        "globalization": {
          "google_client_email": "<SERVICE_ACCOUNT>@<PROJECT_ID>.iam.gserviceaccount.com",
          "google_client_private_key": "<PRIVATE_KEY>",
          "google_document_id": "<SPREADSHEET_DOC_ID>",
          "google_document_sheet_title": "i18nTokens"
        },
        "qrvey_mode": "<QRVEY_MODE>"
      }
    }

    Important: The globalization entry must be a child of variables, not a top-level key and not part of account_config. Make sure the commas before and after the object are correct to preserve the JSON formatting.

    VariableDescription
    google_client_emailService account email created in Step 1: Set up a Google Spreadsheet API (ends in iam.gserviceaccount.com).
    google_client_private_keyValue of private_key from the service account JSON file, including the BEGIN and END lines. Line breaks must stay escaped so the value stays on a single line, for example: -----BEGIN PRIVATE KEY-----\\nMIIEv...\\n-----END PRIVATE KEY-----\\n
    google_document_idDocument ID of the translation spreadsheet.
    google_document_sheet_titleName of the spreadsheet tab used for i18n tokens, for example, i18nTokens.

    Caution: The private key is a secret. Do not commit the configuration file with real credentials to source control or share it in documents, tickets, or chat. Store the key in a secrets manager and inject it at deploy time when possible.

    Create or upgrade the environment with this configuration. When the environment deployment finishes, move to the next step.

Spreadsheet Updates​

The config/spreadsheet is updated automatically when creating or upgrading the environment as a post-deployment step. If the keys change between deployments (for example, adding new datasets or columns, or adding new dynamic labels or i18n tokens in Composer), the user can call the same endpoint manually using a POST request and their API key (see Step 3: Import the Keys). This action re-syncs the spreadsheet with the new or deleted keys.

EndpointBodyPurpose
/translation/config/spreadsheet
/translation/config/dictionary
/translation/config/dictionary/static/tokens		NoneSyncs the Translation Spreadsheet: loads new and deleted keys.

Verify in the Deployment Log​

When the environment is created or upgraded, the automatic execution can be verified in the deployment log, under the post-deployment steps. An HTTP 200 response means the steps completed successfully:

INFO Running post-deployment step: Sync translation spreadsheet via API
   ({{DOMAIN}}/devapi/v5/globalization/translation/config/spreadsheet)
INFO Sync translation spreadsheet via API triggered successfully (HTTP 200).
INFO Running post-deployment step: Generate static files via API
   ({{DOMAIN}}/devapi/v5/globalization/translation/dictionary/actions)
INFO Generate static files via API triggered successfully (HTTP 200).
...
INFO All post-deploy finish-hook API calls succeeded.
INFO Deployment apply process completed successfully.

Step 3: Import the Keys​

In v9.5, complete this step if keys have changed since the last deployment.

  • Recommended Persona: Cloud Ops engineer or Software Developer
  • Prerequisites: Qrvey API key

The Translation Spreadsheet provides the location and mechanism for all translation values. It consists of two tabs, each holding keys and translations for different areas of the Qrvey platform. The keys uniquely identify each term or phrase and are automatically generated for the static text. Dynamic text keys are suggested by the system but can be manually set during the configuration process. See Configuring Dynamic Labels For Datasets to learn more about that process.

The steps in this section use the Qrvey Translation Service Utility to import the keys into the spreadsheet.

Note: To translate dynamic text, it is advisable to configure the desired values before running these steps. This will ensure that the keys for the dynamic values are also imported at this stage.

  1. Obtain the Qrvey API key generated during the deployment process.

  2. From a terminal, call the Update Globalization Spreadsheet endpoint.

    curl --location --request POST '{{DOMAIN}}/devapi/v5/globalization/translation/config/spreadsheet' \
    --header 'content-type: application/json' \
    --header 'x-api-key: {{API_KEY}}'

  3. Open the spreadsheet. See that new keys were added.

Step 4: Add Translations​

  • Recommended Persona: Translators
  • Prerequisites: Access to the Translation Spreadsheet

The Translation Spreadsheet has two tabs by default. The staticText tab is for web page content such as captions, buttons, and menus, and has three important columns that should not be removed:

  • Domain helps identify the area of the product where the static text displays.
  • Key is the unique identifier that the product uses for the term or phrase. Many times it further helps with locating the phrase. The key values should not be changed.
  • Original source is the default English term or phrase that is used in the product. This value is also used as the fallback when no translation exists for the selected language.

Additional columns can be added for each language that has to be supported by the product. Each translation column is named translation_<language-code>. For example, you can add a translation_es column and translate each term that is entered in the original source column to Spanish. See language sub-code and optional national sub-code to learn more about language codes.

A sample row on the static text tab of the spreadsheet can look like the following:

domainkeyoriginal sourcetranslation_estranslation_de
pagebuildertopbar.pagesPagesPáginasSeiten

The i18nTokens tab is used to translate i18n tokens entered into the Qrvey UI. It does not have a domain column. The keys are configured from the Qrvey Composer and can be set to any uniquely identifiable value. It is recommended that the use of special characters is avoided for keys. To learn about the process of configuring i18n tokens in Qrvey Composer, see Configuring Dynamic Labels For Datasets.

After the keys have been added to the spreadsheet by following the import process described in the previous section, any number of people can work on the spreadsheet to enter the translations.

  1. Open the spreadsheet.

  2. Open each of the tabs. Verify that the tabs are loaded with keys.

  3. If they do not already exist, create a column for each language desired.

  4. Enter a translation value for blank cells under the language columns.

You can use standard spreadsheet features to manage the translation process.

  • Sorting the spreadsheet.
  • Reordering columns.
  • Adding row filters. The translation utility ignores row filters.
  • Adding additional working columns for purposes such as translation or QA tracking. The translation utility ignores extra columns.

Note: Do not change the values in the “key” and “original source” columns.

Step 5: Publish the Translated Values​

  • Recommended Persona: Cloud Ops engineer or Software Developer
  • Prerequisites: Qrvey API key

When there are translation values in the spreadsheet, they can be published into Qrvey, making them accessible to the end users who are working with the embedded widgets in different languages.

  1. Obtain the Qrvey API key generated during the deployment process.

  2. From a terminal, call the Update i18n Dictionary Files endpoint.

    curl --location --request POST '{{DOMAIN}}/devapi/v5/globalization/translation/config/dictionary' \
    --header 'content-type: application/json' \
    --header 'x-api-key: {{API_KEY}}'

  3. If you have performed the widget configuration step before (as described in the next section), open the widget and verify the presence of the translated values. Otherwise, complete the process.

Step 6: Configure Qrvey Widgets for Internationalization​

  • Recommended Persona: Software Developer
  • Prerequisites: Language codes of the translated values

Add the necessary setting to the widgets’ configuration object. The i18n object can be added alongside other configuration attributes of the widget and contains lang and an optional locale property:

<script>
var config = {
   "api_key": "<API_KEY>", // your API key
   "app_id": "<APP_ID>", // your app_id
…
   "i18n": {
       "lang": "<language-code>", // the language to use for the UI
       "locale": "<locale-code>", // the optional locale code to use for date and number formatting
   },
…
};
</script>

The values of the lang and locale properties can be a language sub-code and optional national sub-code. For example, specify “es” for Spanish. Or for multiple Spanish dialects, “es-MX” and “es-CO” could be configured for users from Mexico and Colombia.

Alternatively, the value can be “browser”, in which case the browser’s primary language code is selected.

Final Tips​

The following points frequently come up as questions and are worth noting.

Adding Keys in Multiple Rounds​

The process of generating the translation keys is rarely a one-time deal. New keys are identified and must be added for static text due to upgrading to new versions of the product and getting new or updated UI elements. For dynamic text, this can happen even more frequently, as new datasets are added and their column names need translation.

You can repeat Steps 3–6 as needed. Rerunning the utility adds the new keys and preserves previous work.

The process, in the presence of dynamic keys, can be depicted as in the following chart.

internationalization

Language Fallbacks​

When the widget is configured with a language that does not have a translation, the system identifies a fallback language. For example, if the lang property has been set to "es-MX", the system goes through the following steps to choose the correct language:

  1. Use the translation “es-MX”, if it exists.
  2. Use the translation “es”, if it exists.
  3. Use no translation and show the default content.

Setting the Language Dynamically​

The language code can be hard-coded by setting the lang property to a specific language code, or it can be set to the keyword browser to be set dynamically by the user’s browser’s culture setting. If the browser language code does not exist in the translation dictionary, the language fallback process is followed to determine the next language in line.

Formatting Dates and Numbers According to Culture​

Dates and numbers are formatted differently in different regions of the world. While 3/12/2022 is interpreted as March 12, 2022, and 12.345 as 12 point 345 for an American, the same date and number mean December 3, 2022, and twelve thousand three hundred and forty-five for a German user.

For the system to display dates and numbers according to a set culture or the user’s browser settings, the optional locale property of the i18n object can be set to the desired language code or browser, respectively.