Internationalization

This tutorial will teach developers how to correctly use the Bazaarvoice Conversations API to request and submit international content. Developers will first learn how the Bazaarvoice Conversations platform supports internationalization followed by an in-depth discussion of how to localize applications using the Conversations API.

📘

The word "internationalization" is often shortened to "i18n" because there are 18 letters between the first "i" and the last "n".Wikipedia

Platform overview

Building localized software using the Bazaarvoice Conversations API will be easier if you understand how the Bazaarvoice Conversations platform is internationalized. The following sections explain key concepts that will give you insight into what i18n means to Bazaarvoice.

Locale codes

The Bazaarvoice platform support multiple locales which are identified using the language_COUNTRY format. For example:

LocaleLanguageCountry
en_USEnglishUnited States
en_CAEnglishCanada
fr_CAFrenchCanada

🚧

Locale codes are case sensitive.

See the appendix for a list of locales supported by Bazaarvoice.

Content

User submitted content, for example a review, is associated with a particular locale in the Bazaarvoice platform. This serves several purposes including:

  • Allows Bazaarvoice to route content to moderators who understands the language used by the content author
  • API users can use the locale to filter what content the API returns.

Locale is assigned to content during the submission process based on the value identified by the Locale parameter. If no value is supplied the content is assumed to be en_US. See the section Localizing your application with the Conversations API for more details.

The following content types are always associated with a locale:

  • Review
  • Review Comment
  • Question
  • Answer

Client instances

In the Bazaarvoice platform the terms "instance" or "client instance" refer to a data store and the configurations that control available features. In addition each instance has its own Bazaarvoice Workbench. Client instances may contain one or more locales. Typically all Locales will share the same features and configurations, differing only in the language used for Bazaarvoice hosted text (for example, field labels).

📘

An API key is associated with one client instance.

There are several ways in which a client instance may be configured to support international content.

Localization strategies

The localization strategy used for your client instance or instances will influence how you use the Bazaarvoice Conversations API.

Single instance, multiple locale

A localized client of this type will have many locales sharing a single data store and configuration set. Typically client instances using this strategy will have names following the pattern "brandname" or "brandname-language". For example, Acme or Acme-fr.

Clients localized in this way will be able to access all their international content with the same API key and an unfiltered API request will return content from all available locales.

Single instance, single locale

A localized client of this type will have a different data store and configuration set for each locale. Typically client instances using this strategy will have names following the pattern "brand-language_COUNTRY". For example, Acme-en_ca and Acme-fr_ca.

Clients localized in this way will need an API key for each client instance, however there will be no need to filter API requests by local because the available content is only associated with a single local.

Character encoding

The Bazaarvoice platform uses the UTF-8 character encoding. All responses from the Conversations API will use UTF-8 and submissions to the Conversations API should be encoded using UTF-8 and use the application/x-www-form-urlencoded media type. See the appendix for more information.

Localizing your application with the Conversations API

The Conversations API can be used to associate a locale with a particular piece of content, identify the language used for Bazaarvoice hosted labels, and filter and sort requests to control how content is returned. This table summarizes the API options related to localization and the following sections describe how they are used.

OptionContextDescription
Locale={locale_value}Display, SubmissionLocale to display Labels, Configuration, Product Attributes and Category Attributes in. If this parameter is not defined en_US will be assumed.
Locale={locale_value}SubmissionAssociate a locale with a particular piece of content (review, question, etc). If this parameter is not defined en_US will be assumed.
Filter=ContentLocale:{locale_value}DisplayLocale of the content to display. If this filter is not defined, all content regardless of locale is returned.
Sort=ContentLocale:{direction}DisplayDetermines sort order of response based on locale.
Sort=ContentLocale:{locale value}DisplayReturns review in the order of locales you specify. This enables you to first display reviews in the language of your local consumers, followed by reviews in other languages.

For example, Sort=ContentLocale:frCA,en_CA,en_US will return Canadian French reviews followed by Canadian English and then English - United States reviews.

You cannot specify more than 5 locales. Within each locale, reviews are returned in the reverse chronological order by submission time (i.e. recent review first). ContentLocale codes are case-sensitive. Note that wildcard character "
"such as fr_ or en* does not work.

Submission

Submission of non en_US content must include the Locale parameter. The locale parameter performs the following functions:

  • Determines which configured language will be returned for Bazaarvoice hosted field labels

  • Tells the Bazaarvoice platform with what locale to associate the submitted content. Bazaarvoice uses the locale value to route content to human moderators who are fluent in the language used by the content author. This is essential to ensure that the content is moderated correctly.

    🚧

    Content without the correct locale will be rejected by our moderators

Locale specific labels

The language used for field labels returned by Bazaarvoice can be controlled with the Locale parameter. In the following example labels will be returned in Canadian French:

Request

📘

This example is for full submission. If you are using progressive submission, refer this.

https://stg.api.bazaarvoice.com/data/submitreview.json?apiversion=5.4&passkey=qio3og8cf5tnt712gaqfnj1of&productid=test1&Locale=fr_CA

Response

This snippet demonstrates the Locale property of the response, which corresponds to the locale value used in the API request. All Labels in the response will correspond to this value.

{
    "HasErrors": false,
    "Data": {...},
    "Form": [...],
    "AuthorSubmissionToken": null,
    "FormErrors": { },
    "TypicalHoursToPost": 72,
    "SubmissionId": null,
    "Review": {...},
   "Locale": "fr_CA", 
    "Errors": [ ]
}

In this snippet the Label property will be in the language identified by the Locale parameter:

"rating_Value": {
    "Default": null,
    "Value": null,
    "MaxLength": null,
    "Required": false,
    "Type": "IntegerInput",
    "Label": "Quelle note donneriez-vous au rapport qualité-prix de ce produit?",
    "Id": "rating_Value",
    "MinLength": null,
    "Options": [ ]
},

Associating content with locale

The following is an example of a full submission from Canada in the French language. This review will be associated with the fr_CA locale and moderated by a French speaking moderator.

📘

This example is for full submission. If you are using progressive submission, the code will be different.

POST /data/submitreview.json HTTPS/1.1
Host: [stg.]api.bazaarvoice.com
Content-Type: application/x-www-form-urlencoded
X-Forwarded-For: [AuthorIPAddress]
...
ApiVersion=[latestApiVersion]&ProductId=[productId]&Action=submit&Rating=[rating]&ReviewText=[reviewText]
&Title=[title]&UserNickname=[nickname]&PassKey=[yourKey]&fp=[deviceFingerprint]&Locale=fr_CA

Ellipses (...) in above example indicate that your app may generate other headers.

Requesting localized content

Locale specific labels

The language used for field labels returned by Bazaarvoice can be controlled with the Locale parameter. In the following example labels will be returned in Canadian French:

Request

https://stg.api.bazaarvoice.com/data/reviews.json?apiversion=5.4&passkey=qio3og8cf5tnt712gaqfnj1of&Locale=fr_CA

Response

This snippet demonstrates that the Locale property of the response, which corresponds to the local value used in the API request. All Labels in the response will correspond to this value.

{
    "Includes": { },
    "HasErrors": false,
    "Offset": 0,
    "TotalResults": 685,
    "Locale": "fr_CA", 
    "Errors": [ ],
    "Results": [...]
}

In this snippet the Label property will be in the language identified by the Local parameter:

SecondaryRatings": {
    "Value": {
        "Value": 5,
        "ValueLabel": null,
        "MaxLabel": null,
        "Label": "Quelle note donneriez-vous au rapport qualité-prix de ce produit?", 
        "Id": "Value",
        "ValueRange": 5,
        "MinLabel": null,
        "DisplayType": "NORMAL"
    },
...
}

Filtering user submitted content

User submitted content (Reviews, Questions, etc) can be filtered based on locale using the ContentLocale filter.

Single locale

In the following example only content associated with fr_CA will be returned:

Request

https://stg.api.bazaarvoice.com/data/reviews.json?apiversion=5.4&passkey=qio3og8cf5tnt712gaqfnj1of&Locale=fr_CA&Filter=ContentLocale:fr_CA

Response

Show example
{
    "Includes": { },
    "HasErrors": false,
    "Offset": 0,
    "TotalResults": 132,
    "Locale": "fr_CA",
    "Errors": [ ],
    "Results": [
        {
            "TagDimensions": { },
            "TagDimensionsOrder": [ ],
            "AdditionalFieldsOrder": [ ],
            "Cons": null,
            "IsRecommended": true,
            "IsRatingsOnly": false,
            "UserNickname": "ferdinand67",
            "Pros": null,
            "Photos": [],
            "ContextDataValues": { },
            "Videos": [ ],
            "ContextDataValuesOrder": [ ],
            "SubmissionId": null,
            "LastModificationTime": "2014-05-20T13:48:48.000+00:00",
            "TotalFeedbackCount": 2,
            "TotalPositiveFeedbackCount": 1,
            "BadgesOrder": [ ],
            "UserLocation": "Fullerton, CA",
            "Badges": { },
            "AuthorId": "data-gen-user-1xbusbm12yu7d1hn0uh2k2ovc",
            "SecondaryRatingsOrder": [ ],
            "IsFeatured": false,
            "IsSyndicated": false,
            "ProductRecommendationIds": [ ],
            "Title": "Donec vehicula velitdolor.Duis et lectuseros.",
            "ProductId": "Product11",
            "AdditionalFields": { },
            "CampaignId": null,
            "Helpfulness": 0.5,
            "TotalNegativeFeedbackCount": 1,
            "SubmissionTime": "2014-05-19T18:39:00.000+00:00",
            "Rating": 4,
            "ContentLocale": "fr_CA",
            "RatingRange": 5,
            "TotalCommentCount": 0,
            "ReviewText": "Vestibulum et loremest....",
            "ModerationStatus": "APPROVED",
            "ClientResponses": [ ],
            "Id": "1457316",
            "SecondaryRatings": { },
            "CommentIds": [ ],
            "LastModeratedTime": "2014-05-20T13:48:43.000+00:00"
        },
...
}

Multiple locales

Filtering for more than one locale is also possible. This is useful when you know your end-user speak more than one language or when you would like to build a user interface that gives end-users the option of displaying content from more than one locale at a time.

To filter by more than one locale simply concatenate the locals separated by a comma. A wildcard character “” can be used to define the value, e.g., “Filter=Locale:en” returns all content in English (en_US, en_CA, en_GB, etc).

In the following example only content associated with fr_CA and en_CA will be returned:

Request

https://stg.api.bazaarvoice.com/data/reviews.json?apiversion=5.4&passkey=qio3og8cf5tnt712gaqfnj1of&Locale=fr_CA&Filter=ContentLocale:fr_CA,en_CA

Response

Show example
{
    "Includes": { },
    "HasErrors": false,
    "Offset": 0,
    "TotalResults": 132,
    "Locale": "fr_CA",
    "Errors": [ ],
    "Results": [
        {
            "TagDimensions": { },
            "TagDimensionsOrder": [ ],
            "AdditionalFieldsOrder": [ ],
            "Cons": null,
            "IsRecommended": true,
            "IsRatingsOnly": false,
            "UserNickname": "ferdinand67",
            "Pros": null,
            "Photos": [],
            "ContextDataValues": { },
            "Videos": [ ],
            "ContextDataValuesOrder": [ ],
            "SubmissionId": null,
            "LastModificationTime": "2014-05-20T13:48:48.000+00:00",
            "TotalFeedbackCount": 2,
            "TotalPositiveFeedbackCount": 1,
            "BadgesOrder": [ ],
            "UserLocation": "Fullerton, CA",
            "Badges": { },
            "AuthorId": "data-gen-user-1xbusbm12yu7d1hn0uh2k2ovc",
            "SecondaryRatingsOrder": [ ],
            "IsFeatured": false,
            "IsSyndicated": false,
            "ProductRecommendationIds": [ ],
            "Title": "Donec vehicula velitdolor.Duis et lectuseros.",
            "ProductId": "Product11",
            "AdditionalFields": { },
            "CampaignId": null,
            "Helpfulness": 0.5,
            "TotalNegativeFeedbackCount": 1,
            "SubmissionTime": "2014-05-19T18:39:00.000+00:00",
            "Rating": 4,
             "ContentLocale": "fr_CA",
            "RatingRange": 5,
            "TotalCommentCount": 0,
            "ReviewText": "Vestibulum et loremest...",
            "ModerationStatus": "APPROVED",
            "ClientResponses": [ ],
            "Id": "1457316",
            "SecondaryRatings": { },
            "CommentIds": [ ],
            "LastModeratedTime": "2014-05-20T13:48:43.000+00:00"
        },
...
        {
            "TagDimensions": { },
            "TagDimensionsOrder": [ ],
            "AdditionalFieldsOrder": [ ],
            "Cons": null,
            "IsRecommended": true,
            "IsRatingsOnly": false,
            "UserNickname": "imogen31",
            "Pros": null,
            "Photos": [ ],
            "ContextDataValues": { },
            "Videos": [],
            "ContextDataValuesOrder": [ ],
            "SubmissionId": null,
            "LastModificationTime": "2014-05-19T21:11:08.000+00:00",
            "TotalFeedbackCount": 1,
            "TotalPositiveFeedbackCount": 0,
            "BadgesOrder": [ ],
            "UserLocation": "Austin, TX",
            "Badges": { },
            "AuthorId": "data-gen-user-l8u2vwqasf8c7dk8uru6ntjy1",
            "SecondaryRatingsOrder": [ ],
            "IsFeatured": false,
            "IsSyndicated": false,
            "ProductRecommendationIds": [ ],
            "Title": null,
            "ProductId": "data-gen-2qgz8jogyd23fyo749srfoobo",
            "AdditionalFields": { },
            "CampaignId": null,
            "Helpfulness": 0,
            "TotalNegativeFeedbackCount": 1,
            "SubmissionTime": "2014-05-17T19:54:00.000+00:00",
            "Rating": 5,
            "ContentLocale": "en_CA",
            "RatingRange": 5,
            "TotalCommentCount": 0,
            "ReviewText": "Thousands of lives have ...",
            "ModerationStatus": "APPROVED",
            "ClientResponses": [ ],
            "Id": "1456622",
            "SecondaryRatings": { },
            "CommentIds": [ ],
            "LastModeratedTime": "2014-05-19T21:10:41.000+00:00"
        }
}

All locales

To request content from all available locales simple exclude the ContentLocale filter.

🚧

API versions less than or equal to 5.1 do not return all content be default. Latest api version is 5.4 .

Appendix

UTF-8 and application/x-www-form-urlencoded for full submissions

The application/x-www-form-urlencoded media type describes an algorithm for encoding data in a key=value format using hexadecimal percent encoding (%HH) to represent reserved characters and non-ascii characters. The exact percent encoding for a particular character is based not on the characters visual representation, but on the underlying encoding.

Character (Visual) UTF-8 (binary) UTF-8 (hex) Percent encoding
à 11000011 10100000 c3 a0 %c3%a0
11100010 10000010 10101100 e2 82 ac %E2%82%AC
ל 11010111 10011100 d7 9c %D7%9C
11100011 10010000 10001001 e3 90 89 %E3%90%89

Full submissions to the Conversations API should be UTF-8 encoded before applying the application/x-www-form-urlencoded algorithm. Most programming environments can be configured to handle this automatically. The following is a high level generic example demonstrating what the output should look like.

A user writes the following:

**Review Text**
je l'ai eu en solde qualité très bien, taille de la veste un peu grande.

Your application would submit:

📘

This example is for full submission. It does not apply to progressive submission.

POST /data/submitreview.json HTTPS/1.1
Host: [stg.]api.bazaarvoice.com
Content-Type: application/x-www-form-urlencoded
X-Forwarded-For: [AuthorIPAddress]
...
ApiVersion=[latestApiVersion]&ProductId=[productId]&Action=submit&Rating=[rating]&Title=[title]&
ReviewText=je+l'ai+eu+en+solde+qualit%C3%A9+tr%C3%A8s+bien%2C+taille+de+la+veste+un+peu+grande.
&UserNickname=[nickname]&PassKey=[yourKey]&fp=[deviceFingerprint]&Locale=fr_CA

Ellipses (...) in above example indicate that your app may generate other headers.

Note in the above example the "é" and "è" have been percent encoded

Supported Locales

The following table identifies the most commonly used locales available on the Bazaarvoice platform. Some clients, especially those on our Conversations PRR platform, may use other locales. Contact our Support team following the instructions here if you need to know which locales are available for your use.

CountryLanguageLocale
Albania (AL)Albanian (sq)sq_AL
Antigua and Barbuda (AG)English (en)en_AG
Antigua and Barbuda (AG)Spanish (es)es_AG
Argentina (AR)English (en)en_AR
Argentina (AR)Spanish (es)es_AR
Aruba (AW)Dutch (nl)nl_AW
Aruba (AW)English (en)en_AW
Aruba (AW)Spanish (es)es_AW
Australia (AU)English (en)en_AU
Austria (AT)English (en)en_AT
Austria (AT)German (de)de_AT
Bahrain (BH)English (en)en_BH
Belarus (BY)English (en)en_BY
Belarus (BY)Russian (ru)ru_BY
Belgium (BE)Dutch (nl)nl_BE
Belgium (BE)English (en)en_BE
Belgium (BE)French (fr)fr_BE
Belgium (BE)German (de)de_BE
Belize (BZ)English (en)en_BZ
Belize (BZ)Spanish (es)es_BZ
Bolivia (BO)English (en)en_BO
Bolivia (BO)Spanish (es)es_BO
Brazil (BR)English (en)en_BR
Brazil (BR)Portuguese (pt)pt_BR
Bulgaria (BG)Bulgarian (bg)bg_BG
Bulgaria (BG)Dutch (nl)nl_BG
Bulgaria (BG)English (en)en_BG
Canada (CA)English (en)en_CA
Canada (CA)French (fr)fr_CA
Chile (CL)English (en)en_CL
Chile (CL)Spanish (es)es_CL
China (CN)Chinese (zh)zh_CN
China (CN)English (en)en_CN
Colombia (CO)English (en)en_CO
Colombia (CO)Spanish (es)es_CO
Costa Rica (CR)English (en)en_CR
Costa Rica (CR)Spanish (es)es_CR
Croatia (HR)Croatian (hr)hr_HR
Czech Republic (CZ)Czech (cs)cs_CZ
Czech Republic (CZ)English (en)en_CZ
Denmark (DK)Danish (da)da_DK
Denmark (DK)English (en)en_DK
Denmark (DK)German (de)de_DK
Dominican Republic (DO)English (en)en_DO
Dominican Republic (DO)Spanish (es)es_DO
Ecuador (EC)English (en)en_EC
Ecuador (EC)Spanish (es)es_EC
Egypt (EG)English (en)en_EG
El Salvador (SV)English (en)en_SV
El Salvador (SV)Spanish (es)es_SV
Estonia (EE)English (en)en_EE
Estonia (EE)Estonian (et)et_EE
Finland (FI)English (en)en_FI
Finland (FI)Finnish (fi)fi_FI
Finland (FI)Swedish (sv)sv_FI
France (FR)English (en)en_FR
France (FR)French (fr)fr_FR
France (FR)German (de)de_FR
Germany (DE)English (en)en_DE
Germany (DE)French (fr)fr_DE
Germany (DE)German (de)de_DE
Great Britain (GB)English (en)en_GB
Great Britain (GB)French (fr)fr_GB
Great Britain (GB)German (de)de_GB
Greece (GR)English (en)en_GR
Greece (GR)Greek (el)el_GR
Guatemala (GT)English (en)en_GT
Guatemala (GT)Spanish (es)es_GT
Honduras (HN)English (en)en_HN
Honduras (HN)Spanish (es)es_HN
Hong Kong (HK)Chinese (zh)zh_HK
Hong Kong (HK)English (en)en_HK
Hungary (HU)English (en)en_HU
Hungary (HU)Hungarian (hu)hu_HU
Iceland (IS)Icelandic (is)is_IS
India (IN)English (en)en_IN
Indonesia (ID)English (en)en_ID
Indonesia (ID)Indonesian (id)id_ID
Iran (IR)English (en)en_IR
Ireland (IE)English (en)en_IE
Israel (IL)English (en)en_IL
Italy (IT)English (en)en_IT
Italy (IT)German (de)de_IT
Italy (IT)Italian (it)it_IT
Jamaica (JM)English (en)en_JM
Jamaica (JM)Spanish (es)es_JM
Japan (JP)English (en)en_JP
Japan (JP)Japanese (ja)ja_JP
Kazakhstan (KZ)English (en)en_KZ
Kazakhstan (KZ)Russian (ru)ru_KZ
Kenya (KE)English (en)en_KE
Korea (KR)English (en)en_KR
Korea (KR)Korean (ko)ko_KR
Kuwait (KW)English (en)en_KW
Latvia (LV)English (en)en_LV
Latvia (LV)Latvian (lv)lv_LV
Libya (LY)English (en)en_LY
Lithuania (LT)English (en)en_LT
Lithuania (LT)Lithuanian (lt)lt_LT
Luxembourg (LU)English (en)en_LU
Luxembourg (LU)French (fr)fr_LU
Luxembourg (LU)German (de)de_LU
Malaysia (MY)English (en)en_MY
Malaysia (MY)Malay (ms)ms_MY
Mexico (MX)English (en)en_MX
Mexico (MX)Spanish (es)es_MX
Netherlands (NL)Dutch (nl)nl_NL
Netherlands (NL)English (en)en_NL
Netherlands (NL)French (fr)fr_NL
New Zealand (NZ)English (en)en_NZ
Nicaragua (NI)English (en)en_NI
Nicaragua (NI)Spanish (es)es_NI
Nigeria (NG)English (en)en_NG
Norway (NO)English (en)en_NO
Norway (NO)Finnish (fi)fi_NO
Norway (NO)Norwegian (no)no_NO
Oman (OM)English (en)en_OM
Panama (PA)English (en)en_PA
Panama (PA)Spanish (es)es_PA
Paraguay (PY)English (en)en_PY
Paraguay (PY)Spanish (es)es_PY
Peru (PE)English (en)en_PE
Peru (PE)Spanish (es)es_PE
Philippines (PH)English (en)en_PH
Poland (PL)English (en)en_PL
Poland (PL)Polish (pl)pl_PL
Portugal (PT)English (en)en_PT
Portugal (PT)Portuguese (pt)pt_PT
Puerto Rico (PR)English (en)en_PR
Puerto Rico (PR)Spanish (es)es_PR
Qatar (QA)English (en)en_QA
Romania (RO)English (en)en_RO
Romania (RO)Romanian (ro)ro_RO
Russia (RU)English (en)en_RU
Russia (RU)Russian (ru)ru_RU
Saudi Arabia (SA)English (en)en_SA
Serbia (RS)Serbian (sr)sr_RS
Singapore (SG)Chinese (zh)zh_SG
Singapore (SG)English (en)en_SG
Slovakia (SK)English (en)en_SK
Slovakia (SK)Slovak (sk)sk_SK
Slovenia (SI)Slovenian (sl)sl_SI
South Africa (ZA)English (en)en_ZA
Spain (ES)Basque (eu)eu_ES
Spain (ES)Catalan (ca)ca_ES
Spain (ES)English (en)en_ES
Spain (ES)Spanish (es)es_ES
Sudan (SD)English (en)en_SD
Sweden (SE)English (en)en_SE
Sweden (SE)Finnish (fi)fi_SE
Sweden (SE)Swedish (sv)sv_SE
Switzerland (CH)English (en)en_CH
Switzerland (CH)French (fr)fr_CH
Switzerland (CH)German (de)de_CH
Switzerland (CH)Italian (it)it_CH
Taiwan (TW)Chinese (zh)zh_TW
Taiwan (TW)English (en)en_TW
Thailand (TH)English (en)en_TH
Thailand (TH)Thai (th)th_TH
Trinidad and Tobago (TT)English (en)en_TT
Trinidad and Tobago (TT)Spanish (es)es_TT
Turkey (TR)English (en)en_TR
Turkey (TR)Turkish (tr)tr_TR
Ukraine (UA)English (en)en_UA
Ukraine (UA)Russian (ru)ru_UA
Ukraine (UA)Ukrainian (uk)uk_UA
United Arab Emirates (AE)English (en)en_AE
Uruguay (UY)English (en)en_UY
Uruguay (UY)Spanish (es)es_UY
Venezuela (VE)English (en)en_VE
Venezuela (VE)Spanish (es)es_VE
Vietnam (VN)English (en)en_VN
Vietnam (VN)Vietnamese (vi)vi_VN