Internationalization

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.

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.

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:

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
• story
• Story Comment

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

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.

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

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.

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

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.

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.

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:

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

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.