The Conversations API lets you programmatically retrieve and submit Bazaarvoice Conversations data for use in your applications. To learn more, go to the Conversations API documentation home page.

Contents

(+ show- hide)

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:

Locale Language Country
en_US English United States
en_CA English Canada
fr_CA French Canada
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:

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 may only be 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.

Option Context Description
Locale={locale_value} Display, Submission Locale to display Labels, Configuration, Product Attributes and Category Attributes in. If this parameter is not defined en_US will be assumed.
Locale={locale_value} Submission Associate 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} Display Locale of the content to display. If this filter is not defined, all content regardless of locale is returned.
Sort=ContentLocale:{direction} Display Determines sort order of response based on locale.

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, the code will be different.

http://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 HTTP/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

http://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

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

Response

{
    "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

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

Response

{
    "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. See the changelogs for more details.

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 HTTP/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.

c20xx: https://bits.bazaarvoice.com/confluence/pages/viewpage.action?pageId=35675577 prr: https://bits.bazaarvoice.com/confluence/pages/viewpage.action?pageId=21890803 There may be too many to list. Consider listing only c20xx with a note directing developer to Implementation/Support for assistance with other locales.
Locale Language Country
en_US English United States
en_CA English Canada
en_GB English Great Britain
en_AU English Australia
en_NZ English New Zealand
en_IE English Ireland
en_DE English Germany
fr_FR French France
fr_CA French Canada
fr_BE French Belgium
de_DE German Germany
de_AT German Austria
de_CH German Switzerland
es_ES Spanish Spain
es_MX Spanish Mexico
es_CL Spanish Chile
es_CO Spanish Columbia
es_AR Spanish Argentina
es_US Spanish United Statues
nl_NL Dutch Netherlands
nl_BE Dutch Belgium
it_IL Italian Italy
pt_BR Portuguese Brazil
pt_PT Portuguese Portugal
sv_SE Swedish Sweden
zh_CN Chinese, Simplified China
da_DK Danish Denmark
ja_JP Japanese Japan
fi_FL Finnish Finland
no_NO Norwegian Norway
ko_KR Korean Korea
ru_RU Russian Russia
pl_PL Polish Poland
tr_TR Turkish Turkey