There are waste collection programs in many countries. And we always strive to provide our services in the language of the country in question.
This is easy to do in countries that only use one language. In fact, if your application is only ever used in countries with just one language, you don't need to implement anything from this section.
For multi-language countries however (e.g. Canada, the USA where Mexican Spanish is used more and more - we support it, or Switzerland in Europe with its German, French and Italian languages) a method was needed for your application to be able tell our API, which language the current user of your application wants to receive information in. This is what is described in this section.
Usually there is two steps needed to solve this problem:
Get a list of available locales. Only relevant for multi-lingual countries.
Scope: public; this endpoint does not require a logged in user: you can use OAuth2.0 Client Credentials Flow as described in our Getting Started Guide
GET https://api.terracycle.com/en-US/v2/locales?access_token=...access_token...
parameter|description ---|--- accesstoken|the `accesstoken` acquired through OAuth page (optional)| it's used for pagination purposes and it means which page do you want to get, by default is 1 per_page (optional)| it's used for pagination purposes and it means how many items do you want to get within a page, by default is 50
curl -G \
-d 'access_token=acce55acce55acce55acce55acce55acce55acce55acce55acce55acce55acce' \
https://api.terracycle.com/en-US/v2/locales
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Language: en-US
{
"locales": [
{
"locale": "en-US",
"name": "English (US)"
},
{
"locale": "es-US",
"name": "Espa\u00f1ol (US)"
}
]
}
field name|description ---|--- locales|top-level container for the list (array) of locales/languages locale|the commonly used/standardized short code for the locale - usually a combination of language code and country code; in this example en stands for English language, US stands for the USA, so the combination means US English name| human-readable common name for the locale/language - to display to the user to help language selection
Simply provide an HTTP Accept-Language header
with your API request specifying one of the locale values from above,
and we will obey it and return the response in that locale/language.
Example: Accept-Language: en-US
If you specify a locale/language that was not listed by the request above, we will try to use the closest language available if we can guess one, or the default language (first language from the list above) if we could not guess which language would be similar.
This means you are free to use the user's system-wide locale/language preferences as default, and it will usually work. But please still provide the user with the option of calling up this list and choosing another language.
All API endpoints explicitly tell what locale they deducted from your request
and used in responding to it, in the Content-Language header: Content-Language: en-US
During the OAuth authorization flow (described on the Getting Started page) the sign in and authorization screens will be shown to your user by our servers.
The user will probably want to see these screens as well in their own language.
We do process and obey the Accept-Language header for these screens as well,
so if your user's browser provides the correct languages in that header,
you do not have to do anything,
the screens will automatically be shown in the correct language.
In the case you do want to show these screens in another language listed in our language list above, please insert the locale as the first thing into the path of the URL you redirect the user to, and we will obey it and carry it forward to all screens we show to the user.
https://api.terracycle.com/oauth/authorize
This will show the screens in the default language - the first one from the
list above; in our example this will be en-US (US English).
https://api.terracycle.com/es-US/oauth/authorize
This will show the screens in the specified language (assuming that language is
listed above) - es-US (US Spanish).