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:
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:
- 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.
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, refer this.
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
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
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
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.
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 States |
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 |
Updated 3 months ago