RESTful URL: where should I put locale? example.com/en/page vs example.com/page?locale=en

Question

I\'m deciding how to organize URL and put locale into it. I have two choices:

1. example.com/en/page
2. example.com/page?locale=en -- Google way

Answer 1

Localization is part of Content-Negotiation in Restful API.

So my preferred way I would do it through headers. HTTP offers standard way of defining wanted language. Have a look at Accept-Language header.

Answer 2

From https://www.w3.org/International/questions/qa-accept-lang-locales:

The HTTP Accept-Language header was originally only intended to specify the user's language. However, since many applications need to know the locale of the user, common practice has used Accept-Language to determine this information. It is not a good idea to use the HTTP Accept-Language header alone to determine the locale of the user. If you use Accept-Language exclusively, you may handcuff the user into a set of choices not to his liking.

My preference:

• Request
  • use a query parameter
  • fall-back to Accept-Language header if query parameter is not specified
  • fall-back to documented default Locale if Accept-Language header is not defined
• Response
  • Set Content-Language
  • Set locale in response payload, like <some-root-tag xml:lang="en-US"> (see http://www.opentag.com/xfaq_lang.htm)