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
3. en.example.com/page -- isn't good because I'm using subdomains

From one side example.com/en/page looks better and more compact than example.com/page?locale=en. From other side we have two URLs example.com/en/page and example.com/ru/page for one resource with two representations. Of course in case example.com/page?locale=en we have two URLs for one resource too, but it is slightly more RESTful on my taste.

What's the best practice? What are you using and why?

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

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

Comments

[petRUShka]

Yes. I know about Accept-Language. But in Russia, for example, a lot of people use English locale but prefer content in Russian. So if I will use only Accept-Language they will have no chance to change language of content (except of course change locale of browser). Most common solution is language switcher in site layout. So I trying to understand what is is the best way to organizing such switcher.

[manuel aldana]

I see, so your api-client's are browsers (e.g. through AJAX calls)? Then I would go for your proposed url parameter way (like ?lang=en), because the offer you 'optional' semantics (with fallback to Accept-Language header).

[petRUShka]

Browsers and external services. Thanks for your opinion, I'm thinking in the same way.

[Vincent Sels]

I don't see the problem with using Accept-Language. Yes, when your browser sends the HTTP request for a page (likely just your SPA index), it will send the value set in the browser's settings. But for all your requests to the API, using Ajax, surely you can specify any value you'd like for this header - any decent framework will allow you to configure this automatically. So you can still let the user pick a locale from a dropdown list, for instance, and always send that along with every consecutive request.