36

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?

petRUShka
  • 9,812
  • 12
  • 61
  • 95

2 Answers2

50

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.

manuel aldana
  • 15,650
  • 9
  • 43
  • 50
  • 4
    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. – petRUShka Oct 25 '11 at 19:02
  • 3
    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). – manuel aldana Oct 25 '11 at 20:11
  • 1
    Browsers and external services. Thanks for your opinion, I'm thinking in the same way. – petRUShka Oct 25 '11 at 20:51
  • 16
    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. – Vincent Sels May 02 '16 at 14:54
30

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
rmuller
  • 12,062
  • 4
  • 64
  • 92