REST API localization best practice

[Obidul Islam]

Hi,

I am trying to understand best practices for API localization (support multiple language). 

    - Should REST API be language agnostic (return readable meta data) and provide additional API to get translated content?

    - I found that accept-language header is suggested in GET request to get resource from server in user language. Once user get that resource in his/her language how to update that resource? Should PUT/POST request accept localized content?

[Julie C]

I can't speak to "best practice", but I think it is going to depend on what you need to localize.

In our project, once we gave a lot of thought to what needed to be localized, we realized that it was only error messages and status messages, so we decided on the following approach:  

- all messages are prepared from a Message Property File (more specifically, a Java Resource Bundle)

- in the API, we have a specific Representation for "message" responses that includes the localized message, and also includes the property file key along with the list of parameters (if any) used in preparation of the message

- we will attempt to generate the message string localized according to the Accept-Language header.  If there was no Accept-Language header, we will localize according to the system default language

- at the same time, we will publish the Message Property File.  This allows clients to do their own localization based on our property key and parameters if they don't like ours (or we don't support their required language).

We considered a lookup service (and haven't ruled it out), but we have so much core API to implement that it could be a while before we get to it.

As for PUT/POST, in the end we didn't see a localization requirement.  If the data is straight up user data (for example, a tag or a name, or something like that), we maintain/persist the data exactly as it was provided by the client.  If the data is more relational/flag/enum in nature, well, that's just an integer disguised as a string - meaning, we're treating it as a programmatic value that clients probably shouldn't directly expose to the end user, so it doesn't need to be localized in the API (it should only be localized in the presentation layer).

We are intending to provide a lookup service for enum values, but we haven't decided yet whether we provide localization for that.  If we do, we would probably use an algorithm similar to the message algorithm, and once again publish the Property File.

I am interested to see what other people are doing.

Cheers,

Julie

[Eric Johnson]

At our company, I think we've reached almost exactly the same consensus that Julie outlined, with one small difference. We don't bother to localize even the error or status messages. Since the UI already has to be localized, pushing all the localization work to one place apparently has worked best for us. Your decision may depend on the organization of your teams, and your team skill sets, and how much work you do in complex Javascript-based UIs, and how much HTML you generate on the server-side.

Eric.

[Obidul Islam]

Thanks Julie and Eric.

In my team, we decided to go with localized error message. Our REST API response is also localized. Our response contains uniqueId for a field and its value is localized. For example {"testingstatus" : "Not Started_fr"}, _fr means value in french. For predefined field, we validate if the value exist in user's current locale.

Thanks

Obidul